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
A webhook subscription tells watsi which event types to deliver and which HTTPS endpoint should receive them.
Each delivery contains a JSON event with a type, timestamp, workspace identifier, and event-specific data payload.
watsi sends one HTTP POST delivery per matching event. Deliveries are retried when the receiving endpoint fails or times out.
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"
}
}
}Stable event identifier. Use it for deduplication.
Machine-readable event name.
ISO-8601 timestamp for when watsi created the event.
Workspace identifier so one endpoint can serve multiple tenants.
Event-specific payload. See the event catalog for examples.
Delivery headers
Hex-encoded HMAC-SHA256 of the raw request body.
Event type for quick routing, such as message.received.
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.