> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nateq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time events instead of polling.

Webhooks push events to a URL you control the moment something happens in your
workspace, so you don't have to poll the API.

## Set up

Create a webhook from **Settings → Developers → Webhooks** (or via the API with a
`webhooks:manage` key). You provide:

* a **URL** to receive `POST` requests
* the **events** to subscribe to
* a generated **signing secret**

## Payload

Every delivery is a `POST` with this body:

```json theme={null}
{
  "event": "ticket.created",
  "timestamp": "2026-06-30T12:00:00Z",
  "organization_id": "org_...",
  "data": { /* the resource */ },
  "metadata": { "delivery_id": "...", "attempt": 1, "version": "1.0" }
}
```

## Available events

| Event                                                 | Fires when                  |
| ----------------------------------------------------- | --------------------------- |
| `conversation.started`                                | A new conversation begins   |
| `conversation.ended`                                  | A conversation is closed    |
| `conversation.assigned`                               | A conversation is assigned  |
| `message.received`                                    | An inbound message arrives  |
| `message.sent`                                        | An outbound message is sent |
| `ticket.created` / `ticket.updated` / `ticket.closed` | Ticket lifecycle            |
| `broadcast.sent` / `broadcast.failed`                 | Broadcast outcome           |
| `user.created`                                        | A workspace user is created |
| `lead.created`                                        | A new lead is captured      |

<Note>
  Fetch the live, authoritative list any time from
  `GET /api/v1/webhooks/events`.
</Note>

## Verify signatures

Each request is signed with HMAC-SHA256 using your webhook secret. Recompute the
signature over the raw request body and compare it to the signature header before
trusting a payload. Reject anything that doesn't match.

## Retries

Failed deliveries are retried with exponential backoff. Inspect delivery history
and responses under `GET /api/v1/webhooks/{id}/logs`.