# Events

{/* Generated by apps/docs/scripts/webhook-events.ts from the spec snapshot. Edit the event docs in apps/api instead. */}

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

| Event | When |
| --- | --- |
| [`deal.created`](#dealcreated) | New lead |
| [`deal.reopened`](#dealreopened) | Lead is back |
| [`deal.accepted`](#dealaccepted) | Lead accepted |
| [`deal.declined`](#dealdeclined) | Lead declined |
| [`deal.expired`](#dealexpired) | Lead expired |
| [`deal.lost`](#deallost) | Lead lost |
| [`deal.viewing_proposed`](#dealviewing_proposed) | Viewing times offered |
| [`deal.viewing_booked`](#dealviewing_booked) | Viewing booked |
| [`deal.viewing_cancelled`](#dealviewing_cancelled) | Booked viewing cancelled |
| [`deal.contract_signed`](#dealcontract_signed) | Contract signed |
| [`deal.message_created`](#dealmessage_created) | Tenant wrote |
| [`deal.message_sent`](#dealmessage_sent) | Your side wrote |
| [`listing.status_changed`](#listingstatus_changed) | Listing went live or came off the market |
| [`webhook.test`](#webhooktest) | Test |

## The event body

Every event has the same envelope.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Event id, also sent as the `webhook-id` header. The same event is retried with the same id, so use it to drop duplicates. |
| `type` | string | The event type, for example `deal.created`. |
| `createdAt` | string | When the event happened. |
| `data` | object | The 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.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Shace id of the deal. |
| `status` | string | pending: 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. |
| `createdAt` | string | When the tenant showed interest. |
| `statusChangedAt` | string | When 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. |
| `expiresAt` | string or null | When 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. |
| `number` | integer or null | The deal's number at your organization, counting from 1000. Fixed for the deal's life. |
| `reference` | string or null | How 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`. |
| `replyAddress` | string | The 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. |
| `url` | string | The 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. |
| `listing` | object or null | The listing the tenant is interested in; null when the match was not on one of your listings. |
| `listing.id` | string | Shace id of the listing. |
| `listing.externalRef` | string or null | Your reference for the listing. |
| `listing.metadata` | map of string | The `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. |
| `tenant` | object | Who the tenant is. Personal contact details are never shared; use `replyAddress`. |
| `tenant.companyName` | string or null | The tenant's company, as registered or as entered. |
| `tenant.orgNumber` | string or null | The tenant's organization number, when known. |
| `tenant.country` | string | ISO 3166-1 alpha-2 of the organization number. |
| `tenant.underRegistration` | boolean | True when the tenant's company is being registered in Sweden and has no organization number yet; `description` says who they are. |
| `tenant.description` | string or null | The tenant's own description of their business, given instead of an organization number while the company is under registration. Null otherwise. |
| `request` | object | What the tenant asked for. The listed codes are the current ones; treat an unknown value as free text. |
| `request.city` | string | Where they are looking: `stockholm`, `gothenburg` or `malmo`, or the city the tenant typed in. |
| `request.teamSize` | string or null | Number of people. |
| `request.areaM2Min` | string or null | Smallest area in m². |
| `request.areaM2Max` | string or null | Largest area in m². |
| `request.moveIn` | string | When they want to move in: `asap`, `1-3m`, `3-6m` or `6+m` (months from the request). |
| `request.term` | string | How long they want to stay: `flexible`, `6-12m`, `1-2y` or `2+y`. |

```json
{
  "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:

| Field | Type | Description |
| --- | --- | --- |
| `data.viewing` | object | The viewing times offered. |
| `data.viewing.id` | string | Shace id of the viewing; `deal.viewing_booked` carries the same id when the tenant picks a time. |
| `data.viewing.slots` | array of object | The times the tenant can pick from, earliest first. Empty once the round is withdrawn. |
| `data.viewing.slots[].startsAt` | string | When the viewing starts. |
| `data.viewing.source` | string | Where the times were offered: `app` in Shace, `email` read from a mail to the reply address. |

```jsonc
{
  "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:

| Field | Type | Description |
| --- | --- | --- |
| `data.viewing` | object | The viewing the tenant booked. |
| `data.viewing.id` | string | Shace id of the viewing. |
| `data.viewing.startsAt` | string | When the viewing starts. |

```jsonc
{
  "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:

| Field | Type | Description |
| --- | --- | --- |
| `data.viewing` | object | The viewing that was booked. |
| `data.viewing.id` | string | Shace id of the viewing. |
| `data.viewing.startsAt` | string | When the viewing was to start. |

```jsonc
{
  "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:

| Field | Type | Description |
| --- | --- | --- |
| `data.contract` | object | The contract both parties signed. |
| `data.contract.id` | string | Shace id of the contract. |
| `data.contract.signedAt` | string | When the last signature landed. |

```jsonc
{
  "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:

| Field | Type | Description |
| --- | --- | --- |
| `data.message` | object | The tenant's message. |
| `data.message.id` | string | Shace id of the message. |
| `data.message.body` | string | The text, as written. |
| `data.message.attachments` | array of object | Attached files; the mail carries the files. |
| `data.message.attachments[].name` | string | File name. |
| `data.message.attachments[].mimeType` | string | MIME type. |
| `data.message.attachments[].size` | integer | Size in bytes. |
| `data.message.createdAt` | string | When it was sent. |

```jsonc
{
  "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:

| Field | Type | Description |
| --- | --- | --- |
| `data.message` | object | The message from your side. |
| `data.message.id` | string | Shace id of the message. |
| `data.message.body` | string | The 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.attachments` | array of object | Attached files that reached the chat. |
| `data.message.attachments[].name` | string | File name. |
| `data.message.attachments[].mimeType` | string | MIME type. |
| `data.message.attachments[].size` | integer | Size in bytes. |
| `data.message.createdAt` | string | When it was sent. |
| `data.message.via` | string | Where it was written: `app` in Shace, `email` by a mail to the reply address, `api` with `POST /deals/{id}/accept`. |
| `data.message.from` | object | Who wrote it. |
| `data.message.from.email` | string | The member's email in your organization. |
| `data.message.from.name` | string or null | Their name in Shace, when known. |

```jsonc
{
  "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.

| Field | Type | Description |
| --- | --- | --- |
| `data.listing` | object | Your listing as it is now. |
| `data.listing.id` | string | Shace id of the listing. |
| `data.listing.externalRef` | string | Your reference for the listing. |
| `data.listing.status` | string | The listing's status now. |
| `data.listing.publishBlockers` | array of string | What keeps it from going live; empty when nothing does. |
| `data.listing.metadata` | map of string | The `metadata` you pushed on the listing. |
| `data.previousStatus` | string | The status before the change. |

```json
{
  "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.

| Field | Type | Description |
| --- | --- | --- |
| `data.endpointId` | string | The endpoint being tested. |

```json
{
  "id": "9a7c5e3b-1f2d-4b6a-8c0e-2d4f6a8b0c1e",
  "type": "webhook.test",
  "createdAt": "2026-09-24T09:12:40.130Z",
  "data": {
    "endpointId": "b7e4c2a9-1d3f-4e6b-8a5c-9f0d2e7b4c16"
  }
}
```
