Webhook events

Soosh sends a POST to your webhook endpoint when something happens in your workspace. Pick the events in Settings > Webhooks, or with POST /v1/webhooks.

Signed the Standard Webhooks way. Verify webhooks has the code.
Answer with any 2xx within 10 seconds. Anything else is tried up to 11 times over about 52 hours.
An event can come more than once. Drop one whose id you’ve seen.
Events can arrive out of order. Order them by at in message.status, by updated_at where the object has one, and otherwise by the envelope’s created_at.

Webhook delivery has the request, the retries and when an endpoint is paused or turned off.

Events

Each group is a feature of your plan. Over the API, subscribing also needs the group’s scope.

Messages

Plan feature webhooks.messages · Scope messages:read

message.received

Message received

Occurs when A customer’s message is stored.

message

message.sent

Message sent

Occurs when WhatsApp accepts an outgoing message.

message

message.status

Message status changed

Occurs when An outgoing message is delivered, read or fails.

Own fields

Contacts

Plan feature webhooks.contacts · Scope contacts:read

contact.created

Contact created

Occurs when A new contact is added, or a deleted one comes back.

contact

contact.updated

Contact updated

Occurs when A contact’s name, attributes, tags, opt-out or number changes.

Own fields

contact.deleted

Contact deleted

Occurs when A contact is deleted.

Own fields

Templates

Plan feature webhooks.templates · Scope templates:read

template.status

Template status changed

Occurs when WhatsApp reports a new status for a template.

Own fields

Chats

Plan feature webhooks.chats · Scope chats:write

chat.assigned

Chat assigned

Occurs when The agent or team a chat is with changes.

Own fields

chat.closed

Chat closed

Occurs when A chat is closed.

Own fields

chat.reopened

Chat reopened

Occurs when A closed chat is open again.

Own fields

Broadcasts

Plan feature webhooks.broadcasts · Scope broadcasts:read

broadcast.status

Broadcast status changed

Occurs when A broadcast’s status changes, starting when it is created.

broadcast

Testing. 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"}.

The envelope

Every event has this shape. Only type and data change.

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.
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.

contact.created

{
  "id": "evt_b62f56f0eff4d5e7fee62e866666198d",
  "type": "contact.created",
  "api_version": "2026-10-14",
  "created_at": "2026-10-14T09:05:11.634Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
    "phone": "+919876543210",
    "whatsapp_user_id": null,
    "name": "Priya Sharma",
    "whatsapp_name": null,
    "attributes": {
      "customer_id": "8812",
      "city": "Pune",
      "orders": 3
    },
    "tags": [
      "VIP"
    ],
    "marketing_opt_out": false,
    "number_id": null,
    "chat": {
      "status": "open",
      "assigned_agent_id": null,
      "last_message_at": null,
      "last_inbound_at": null
    },
    "created_at": "2026-10-14T09:05:11.420Z",
    "updated_at": "2026-10-14T09:05:11.420Z"
  }
}