# Webhook events

Soosh sends a `POST` to your endpoint when something happens in your workspace. Events are signed the Standard Webhooks way. Answer any 2xx within 10 seconds. An event can come twice (its `id` is the same on every try), and events can arrive out of order: order them by the times in `data`.
Delivery, retries and turned-off endpoints: https://docs.soosh.io/reference/webhook-delivery/

## The envelope

- `id`: The event's ID, starting `evt_`. It is the same on every try and for every endpoint. To drop duplicates, use it or the `webhook-id` header, the delivery's ID, which also stays the same on every try. See [Verify webhooks](/guides/api/verify-webhooks/).
- `type`: The event, such as `message.status`. New events may be added.
- `api_version`: The version of the event shapes, such as `2026-10-14`.
- `created_at`: When the event happened. RFC 3339, UTC, with milliseconds.
- `workspace_id`: Your workspace's ID.
- `data`: The event's object, shown on the event's own page. For `message.received`, `message.sent`, `contact.created` and `broadcast.status` it is the same object the API returns.

## Messages

Plan feature `webhooks.messages`. Scope `messages:read`.

- [`message.received`](https://docs.soosh.io/reference/api/webhook-events/message-received/) (Message received): A customer's message is stored.
- [`message.sent`](https://docs.soosh.io/reference/api/webhook-events/message-sent/) (Message sent): WhatsApp accepts an outgoing message.
- [`message.status`](https://docs.soosh.io/reference/api/webhook-events/message-status/) (Message status changed): An outgoing message is delivered, read or fails.

## Contacts

Plan feature `webhooks.contacts`. Scope `contacts:read`.

- [`contact.created`](https://docs.soosh.io/reference/api/webhook-events/contact-created/) (Contact created): A new contact is added, or a deleted one comes back.
- [`contact.updated`](https://docs.soosh.io/reference/api/webhook-events/contact-updated/) (Contact updated): A contact's name, attributes, tags, opt-out or number changes.
- [`contact.deleted`](https://docs.soosh.io/reference/api/webhook-events/contact-deleted/) (Contact deleted): A contact is deleted.

## Templates

Plan feature `webhooks.templates`. Scope `templates:read`.

- [`template.status`](https://docs.soosh.io/reference/api/webhook-events/template-status/) (Template status changed): WhatsApp reports a new status for a template.

## Chats

Plan feature `webhooks.chats`. Scope `chats:write`.

- [`chat.assigned`](https://docs.soosh.io/reference/api/webhook-events/chat-assigned/) (Chat assigned): The agent or team a chat is with changes.
- [`chat.closed`](https://docs.soosh.io/reference/api/webhook-events/chat-closed/) (Chat closed): A chat is closed.
- [`chat.reopened`](https://docs.soosh.io/reference/api/webhook-events/chat-reopened/) (Chat reopened): A closed chat is open again.

## Broadcasts

Plan feature `webhooks.broadcasts`. Scope `broadcasts:read`.

- [`broadcast.status`](https://docs.soosh.io/reference/api/webhook-events/broadcast-status/) (Broadcast status changed): A broadcast's status changes, starting when it is created.

**Test webhook** in the app sends an event of type `webhook.test`, which you don't subscribe to. Its `data` is `{"test": true, "message": "This is a test event from Soosh"}`.