Shace
Webhooks

Events

Shace sends these events to your webhook endpoints as signed POST requests. Overview covers delivery, signatures and retries. An endpoint gets every event; deal events (deal.*) are sent with full integration only.

EventWhen
deal.createdNew lead
deal.reopenedLead is back
deal.acceptedLead accepted
deal.declinedLead declined
deal.expiredLead expired
deal.lostLead lost
deal.viewing_proposedViewing times offered
deal.viewing_bookedViewing booked
deal.viewing_cancelledBooked viewing cancelled
deal.contract_signedContract signed
deal.message_createdTenant wrote
deal.message_sentYour side wrote
listing.status_changedListing went live or came off the market
webhook.testTest

The event body

Every event has the same envelope.

FieldTypeDescription
idstringEvent id, also sent as the webhook-id header. The same event is retried with the same id, so use it to drop duplicates.
typestringThe event type, for example deal.created.
createdAtstringWhen the event happened.
dataobjectThe payload. What it holds depends on type.

The deal

Every deal.* event carries the whole deal as data.deal, in the shape GET /deals/{id} returns.

FieldTypeDescription
idstringShace id of the deal.
statusstringpending: waiting for your answer. accepted: you took the tenant on and the conversation is open. declined: you said no. expired: nobody answered in time. lost: the tenant withdrew or Shace closed it.
createdAtstringWhen the tenant showed interest.
statusChangedAtstringWhen the deal entered its current status. Events that do not change the status (a viewing, a message) keep it. Neither this nor an event's createdAt guarantees the order events arrive in; when order matters, read the deal.
expiresAtstring or nullWhen a pending deal expires unanswered; null in every other status. Expiry runs nightly, so the deal can still be answered until that run; deal.expired follows it.
numberinteger or nullThe deal's number at your organization, counting from 1000. Fixed for the deal's life.
referencestring or nullHow people refer to the deal, like VAS-1042: your organization's prefix and the deal's number. Show it to your staff; key your records on id.
replyAddressstringThe tenant's contact address for this deal. Store it as the lead's email: the tenant's messages arrive from it, and mail your staff send to it reaches the tenant's chat. The first mail to a pending deal accepts it.
urlstringThe deal in Shace, for people with an account. Its form follows the status: /dashboard/deals?peek=<reference> (the lead) while pending, /chats/<id> (the conversation) once accepted, /dashboard/deals after that. Take it as a link; do not parse it.
listingobject or nullThe listing the tenant is interested in; null when the match was not on one of your listings.
listing.idstringShace id of the listing.
listing.externalRefstring or nullYour reference for the listing.
listing.metadatamap of stringThe metadata you pushed on the listing, to route the lead. In an event it is the metadata when the event was created; GET /deals/{id} returns the listing's current metadata.
tenantobjectWho the tenant is. Personal contact details are never shared; use replyAddress.
tenant.companyNamestring or nullThe tenant's company, as registered or as entered.
tenant.orgNumberstring or nullThe tenant's organization number, when known.
tenant.countrystringISO 3166-1 alpha-2 of the organization number.
tenant.underRegistrationbooleanTrue when the tenant's company is being registered in Sweden and has no organization number yet; description says who they are.
tenant.descriptionstring or nullThe tenant's own description of their business, given instead of an organization number while the company is under registration. Null otherwise.
requestobjectWhat the tenant asked for. The listed codes are the current ones; treat an unknown value as free text.
request.citystringWhere they are looking: stockholm, gothenburg or malmo, or the city the tenant typed in.
request.teamSizestring or nullNumber of people.
request.areaM2Minstring or nullSmallest area in m².
request.areaM2Maxstring or nullLargest area in m².
request.moveInstringWhen they want to move in: asap, 1-3m, 3-6m or 6+m (months from the request).
request.termstringHow long they want to stay: flexible, 6-12m, 1-2y or 2+y.
JSONCode
{ "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30", "status": "pending", "createdAt": "2026-09-24T09:12:40.118Z", "statusChangedAt": "2026-09-24T09:12:40.118Z", "expiresAt": "2026-10-08T09:12:40.118Z", "number": 1042, "reference": "VAS-1042", "replyAddress": "vas-1042@chat.shace.se", "url": "https://www.shace.se/dashboard/deals?peek=VAS-1042", "listing": { "id": "5c1c8f0e-6a3b-4a4c-9a3e-2b7f0d9a1e11", "externalRef": "unit-4711", "metadata": { "responsibleId": "E-4411" } }, "tenant": { "companyName": "Lumen Design AB", "orgNumber": "5591234567", "country": "SE", "underRegistration": false, "description": null }, "request": { "city": "stockholm", "teamSize": "8", "areaM2Min": "100", "areaM2Max": "150", "moveIn": "1-3m", "term": "1-2y" } }

Deal events

deal.created

New lead. A tenant is interested in one of your listings and waits for your answer. Create the lead in your system and store deal.replyAddress as its email.

data.deal.status is pending.

deal.reopened

Lead is back. A lead your organization already heard about is pending again, usually because a tenant who withdrew is interested again. Same id and reply address. Sent only when an earlier event about this deal reached your organization; a lead that reaches you for the first time arrives as deal.created, even after an earlier withdrawal. If your system has no record of the deal (say your endpoint skipped deal.created), create it from this event.

data.deal.status is pending.

deal.accepted

Lead accepted. The deal was accepted, through the API, by a mail to the reply address, or in Shace. The conversation with the tenant is open.

data.deal.status is accepted.

deal.declined

Lead declined. Your organization declined the lead.

data.deal.status is declined.

deal.expired

Lead expired. Nobody answered the lead before expiresAt. The tenant has moved on.

data.deal.status is expired.

deal.lost

Lead lost. The tenant withdrew their interest, or Shace closed the lead. A withdrawal can be undone by the tenant, which sends deal.reopened.

data.deal.status is lost.

deal.viewing_proposed

Viewing times offered. Your side offered the tenant viewing times to pick from: in Shace, or by a mail to the reply address that names times (Shace reads them and offers them as a pick-a-time card). Every new round sends it, and a new round replaces the one before: an upcoming booked viewing it replaces sends deal.viewing_cancelled. When the offered times of a round change in Shace, it is sent again with the same viewing id and the current times; the latest one is current. A round your side withdraws in Shace is sent again with the same id and no slots.

data.deal.status is accepted.

Next to data.deal, the event carries:

FieldTypeDescription
data.viewingobjectThe viewing times offered.
data.viewing.idstringShace id of the viewing; deal.viewing_booked carries the same id when the tenant picks a time.
data.viewing.slotsarray of objectThe times the tenant can pick from, earliest first. Empty once the round is withdrawn.
data.viewing.slots[].startsAtstringWhen the viewing starts.
data.viewing.sourcestringWhere the times were offered: app in Shace, email read from a mail to the reply address.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "deal.viewing_proposed", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "deal": { "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30", "status": "accepted" /* …the rest of the deal */ }, "viewing": { "id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "slots": [ { "startsAt": "2026-09-30T08:00:00.000Z" }, { "startsAt": "2026-10-01T12:00:00.000Z" } ], "source": "email" } } }

deal.viewing_booked

Viewing booked. The tenant booked one of the viewing times offered.

data.deal.status is accepted.

Next to data.deal, the event carries:

FieldTypeDescription
data.viewingobjectThe viewing the tenant booked.
data.viewing.idstringShace id of the viewing.
data.viewing.startsAtstringWhen the viewing starts.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "deal.viewing_booked", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "deal": { "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30", "status": "accepted" /* …the rest of the deal */ }, "viewing": { "id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "startsAt": "2026-09-30T08:00:00.000Z" } } }

deal.viewing_cancelled

Booked viewing cancelled. A booked viewing that has not taken place yet is off because your side offered new times, in Shace or by mail. deal.viewing_proposed with the new times comes with it.

data.deal.status is accepted.

Next to data.deal, the event carries:

FieldTypeDescription
data.viewingobjectThe viewing that was booked.
data.viewing.idstringShace id of the viewing.
data.viewing.startsAtstringWhen the viewing was to start.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "deal.viewing_cancelled", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "deal": { "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30", "status": "accepted" /* …the rest of the deal */ }, "viewing": { "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e", "startsAt": "2026-09-30T08:00:00.000Z" } } }

deal.contract_signed

Contract signed. Both parties signed the contract. A signed renewal sends it again, with the new contract.

data.deal.status is accepted.

Next to data.deal, the event carries:

FieldTypeDescription
data.contractobjectThe contract both parties signed.
data.contract.idstringShace id of the contract.
data.contract.signedAtstringWhen the last signature landed.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "deal.contract_signed", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "deal": { "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30", "status": "accepted" /* …the rest of the deal */ }, "contract": { "id": "c9d8e7f6-a5b4-4c3d-9e2f-1a0b9c8d7e6f", "signedAt": "2026-10-14T15:22:41.000Z" } } }

deal.message_created

Tenant wrote. The tenant wrote in the chat. The same message is mailed from the deal's reply address to whoever last wrote from your side, so you only need this to route it yourself. Messages from your side send deal.message_sent.

data.deal.status is accepted.

Next to data.deal, the event carries:

FieldTypeDescription
data.messageobjectThe tenant's message.
data.message.idstringShace id of the message.
data.message.bodystringThe text, as written.
data.message.attachmentsarray of objectAttached files; the mail carries the files.
data.message.attachments[].namestringFile name.
data.message.attachments[].mimeTypestringMIME type.
data.message.attachments[].sizeintegerSize in bytes.
data.message.createdAtstringWhen it was sent.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "deal.message_created", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "deal": { "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30", "status": "accepted" /* …the rest of the deal */ }, "message": { "id": "5d4c3b2a-1f0e-4d9c-8b7a-6e5f4d3c2b1a", "body": "Hej! Passar torsdag kl 10 för en visning?", "attachments": [], "createdAt": "2026-09-24T14:02:10.000Z" } } }

deal.message_sent

Your side wrote. Someone on your side wrote to the tenant: in Shace, by a mail to the reply address, or with an accept through the API. For a mail, body is what the tenant sees in the chat, after Shace left out the quoted history and the signature, so you can check what came through. Use via to skip messages your own system sent.

data.deal.status is accepted.

Next to data.deal, the event carries:

FieldTypeDescription
data.messageobjectThe message from your side.
data.message.idstringShace id of the message.
data.message.bodystringThe text as the tenant sees it; empty when only files were sent. Viewing times read from a mail are left out of it, since the tenant gets them as a pick-a-time card (deal.viewing_proposed).
data.message.attachmentsarray of objectAttached files that reached the chat.
data.message.attachments[].namestringFile name.
data.message.attachments[].mimeTypestringMIME type.
data.message.attachments[].sizeintegerSize in bytes.
data.message.createdAtstringWhen it was sent.
data.message.viastringWhere it was written: app in Shace, email by a mail to the reply address, api with POST /deals/{id}/accept.
data.message.fromobjectWho wrote it.
data.message.from.emailstringThe member's email in your organization.
data.message.from.namestring or nullTheir name in Shace, when known.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "deal.message_sent", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "deal": { "id": "3f6b1d2e-8c47-4a0e-9f5d-7b2c1e4a9d30", "status": "accepted" /* …the rest of the deal */ }, "message": { "id": "7b6a5c4d-3e2f-4a1b-9c8d-0e1f2a3b4c5d", "body": "Hej! Torsdag kl 10 passar bra. Portkoden är 1430.", "attachments": [ { "name": "planritning.pdf", "mimeType": "application/pdf", "size": 184320 } ], "createdAt": "2026-09-24T14:20:31.000Z", "via": "email", "from": { "email": "anna@landlord.se", "name": "Anna Lind" } } } }

Listing events

listing.status_changed

Listing went live or came off the market. One of your pushed listings changed status, whoever changed it: your own push, someone in Shace, or Shace support. Use it to keep your publish flag in step. A first push that creates a listing sends no event; its status is in the response.

FieldTypeDescription
data.listingobjectYour listing as it is now.
data.listing.idstringShace id of the listing.
data.listing.externalRefstringYour reference for the listing.
data.listing.statusstringThe listing's status now.
data.listing.publishBlockersarray of stringWhat keeps it from going live; empty when nothing does.
data.listing.metadatamap of stringThe metadata you pushed on the listing.
data.previousStatusstringThe status before the change.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "listing.status_changed", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "listing": { "id": "5c1c8f0e-6a3b-4a4c-9a3e-2b7f0d9a1e11", "externalRef": "unit-4711", "status": "unpublished", "publishBlockers": [], "metadata": { "responsibleId": "E-4411" } }, "previousStatus": "published" } }

Test event

webhook.test

Test. Sent by POST /webhooks/{id}/test or the dashboard's test button to that endpoint only, once, without retries.

FieldTypeDescription
data.endpointIdstringThe endpoint being tested.
JSONCode
{ "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e", "type": "webhook.test", "createdAt": "2026-09-24T09:12:40.130Z", "data": { "endpointId": "b7e4c2a9-1d3f-4e6b-8a5c-9f0d2e7b4c16" } }
Last modified on