Webhooks

Watsi webhooks let your system receive event notifications without polling. Use them to react to new inbound messages, delivery status changes, and conversation or contact updates in near real time.

Core concepts

Subscriptions

A webhook subscription tells Watsi which event types to deliver and which HTTPS endpoint should receive them.

Events

Each delivery contains a JSON event with a type, timestamp, workspace identifier, and event-specific data payload.

Deliveries

Watsi sends one HTTP POST delivery per matching event. Deliveries are retried when the receiving endpoint fails or times out.

Signing

Every delivery includes an HMAC-SHA256 signature in the X-Watsi-Signature header so your server can verify authenticity before processing the payload.

Delivery request shape

Watsi sends webhook deliveries as HTTPS POST requests with a JSON body. The exact event-specific payload varies by event type, but the top-level envelope remains stable.

{
  "id": "evt_01HXYZ123456789",
  "type": "message.received",
  "created_at": "2025-03-15T10:30:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "message": {
      "id": "wamid.HBgL...",
      "body": "Hola"
    }
  }
}

Field	Meaning
`id`	Stable event identifier. Use it for deduplication.
`type`	Machine-readable event name.
`created_at`	ISO-8601 timestamp for when Watsi created the event.
`workspace_id`	Workspace identifier so one endpoint can serve multiple tenants.
`data`	Event-specific payload. See the event catalog for examples.

Delivery headers

Header	Purpose
`X-Watsi-Signature`	Hex-encoded HMAC-SHA256 of the raw request body.
`X-Watsi-Event`	Event type for quick routing, such as message.received.
`X-Watsi-Delivery-Id`	Unique delivery identifier for log correlation and deduplication.

Always verify X-Watsi-Signature against the raw request body before parsing JSON.

Delivery guarantees

Webhooks are delivered on an at least once basis. A transient network or application failure can cause the same event to be delivered more than once, so handlers should be idempotent.

Your endpoint should acknowledge deliveries quickly with a 2xx response and move longer work to background processing.

Retry policy

Watsi retries unsuccessful deliveries with increasing backoff until the final attempt is exhausted.

Attempt	Notes
1	Initial delivery
2	Short retry after a transient failure
3	Backoff retry
4	Longer backoff retry
5	Final retry before the delivery is marked failed

Exact timing may evolve, but integrations should assume increasing backoff and should not rely on fixed retry timestamps.

Continue reading

Signing & verification guide — verify the HMAC signature in Node.js, Python, Ruby, Go, or PHP.
Event catalog — inspect the documented event types and example payloads.
End-to-end tutorial — register a subscription, receive an event, and validate its signature.