# Webhooks

> Overview of the watsi webhook model — subscriptions, event envelopes, headers, delivery guarantees, and retry behavior.

Source: https://docs.watsi.ai/en/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.

```json Event envelope
{
  "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"
    }
  }
}
```

- `id` (string)
  Stable event identifier. Use it for deduplication.
- `type` (string)
  Machine-readable event name.
- `created_at` (string)
  ISO-8601 timestamp for when watsi created the event.
- `workspace_id` (string)
  Workspace identifier so one endpoint can serve multiple tenants.
- `data` (object)
  Event-specific payload. See the [event catalog](/webhooks/events) for examples.

## Delivery headers

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

> **Warning**

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 |

> **Note**

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

## Continue reading

- [Signing & verification guide](/webhooks/signing)
    Verify the HMAC signature in Node.js, Python, Ruby, Go, or PHP.
- [Event catalog](/webhooks/events)
    Inspect the documented event types and example payloads.
- [End-to-end tutorial](/webhooks/tutorial)
    Register a subscription, receive an event, and validate its signature.