> ## Documentation Index
> Fetch the complete documentation index at: https://docs.d-api.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

> How to configure, receive and process the events of a WhatsApp session.

Webhooks notify your system in real time about what happens in each
unofficial WhatsApp **session**: received and sent messages, status changes,
connection events, chat/contact updates and group activity.

## Per-session configuration

Each session has its own webhook configuration, with two delivery modes:

> [accordion] single — one URL for all events
>
> All **enabled** events of the session are sent to the same URL.
> Useful when a single endpoint handles all the processing.

> [accordion] per\_event — one URL per event
>
> Each event has its own `webhookUrl`, so you can route different events
> to different endpoints.

Regardless of the mode, each event has:

**enabled** `boolean`

Turns delivery of the event on or off. **Disabled events are not sent**.

**webhookUrl** `string`

Destination URL of the event (in `per_event` mode) or inherited from the single
configuration (in `single` mode).

## Common envelope

Every webhook arrives with the same envelope. The event-specific content
is in `data`.

```json theme={null}
{
  "event": "messages.received",
  "sessionId": "my-session",
  "data": { "...": "event-specific" },
  "timestamp": "2026-01-24T22:51:32.601Z",
  "traceId": "c17dee440402792623e3ad6d925cb000"
}
```

**event** `string` *required*

Event name (e.g. `messages.received`).

**sessionId** `string` *required*

ID of the session that originated the event.

**data** `object` *required*

Event-specific content. See each event's page.

**timestamp** `string` *required*

Date and time of delivery in ISO 8601 (UTC).

**traceId** `string`

Identifier for end-to-end tracing. Useful in logs and support requests.

## Headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `User-Agent` | `Deliverify-Webhook/1.0` |

> [!NOTE]
>
> This product does **not** send an HMAC signature with webhooks. To restrict the
> origin, we recommend using a secret URL (with a token in the path) and/or validating the
> `User-Agent` and the expected `sessionId`.

## Delivery and reliability

> [accordion] Retries (7 attempts, exponential backoff)
>
> On failure, delivery is retried up to **7 times** with exponential
> backoff: approximately **5s, 10s, 20s, 40s, 80s and 160s** between
> attempts.

> [accordion] Permanent failures (404 / 410)
>
> HTTP **404** or **410** responses are treated as a **permanent failure**:
> delivery is no longer retried for that URL.

> [accordion] Timeout
>
> Each attempt has a **30-second** timeout. Slow endpoints may be
> considered a failure and be retried.

> [accordion] Circuit breaker
>
> There is a **per-URL circuit breaker**: URLs that fail repeatedly are
> temporarily paused to avoid overload.

> [accordion] Deduplication
>
> Events go through **Redis-based deduplication** (5-minute TTL), reducing
> duplicate deliveries of the same event within a short interval.

> [!WARNING]
>
> Respond quickly with a **2xx** status. Do heavy processing
> asynchronously (queue/worker) and acknowledge receipt as soon as possible to
> avoid timeouts (30s) and unnecessary retries.

## Available events

| Event | Description | Page |
| - | - | - |
| `messages.received` | Message received | [messages.received](https://docs.d-api.cloud/en/whatsapp/webhooks/messages-received.md) |
| `messages.sent` | Message sent by the session | [messages.sent](https://docs.d-api.cloud/en/whatsapp/webhooks/messages-sent.md) |
| `message.read` | Message read | [Message status](https://docs.d-api.cloud/en/whatsapp/webhooks/status-de-mensagens.md) |
| `message.delivered` | Message delivered | [Message status](https://docs.d-api.cloud/en/whatsapp/webhooks/status-de-mensagens.md) |
| `message.deleted` | Message deleted | [Message status](https://docs.d-api.cloud/en/whatsapp/webhooks/status-de-mensagens.md) |
| `message.update` | Not fired — edits arrive in `messages.received` with `type: "edited_message"` | [Message status](https://docs.d-api.cloud/en/whatsapp/webhooks/status-de-mensagens.md) |
| `session.created` | Official API connection provisioned by the hosted connect flow | [Connection](https://docs.d-api.cloud/en/whatsapp/webhooks/conexao.md) |
| `connection.qrcode` | QR code generated | [Connection](https://docs.d-api.cloud/en/whatsapp/webhooks/conexao.md) |
| `connection.paircode` | Pairing code generated | [Connection](https://docs.d-api.cloud/en/whatsapp/webhooks/conexao.md) |
| `connection.status` | Connection status change | [Connection](https://docs.d-api.cloud/en/whatsapp/webhooks/conexao.md) |
| `logged_out` | Session logged out | [Connection](https://docs.d-api.cloud/en/whatsapp/webhooks/conexao.md) |
| `chats.update` | Chat updated | [Chats, contacts and presence](https://docs.d-api.cloud/en/whatsapp/webhooks/chats-contatos-presenca.md) |
| `chats.upsert` | Chat created/updated | [Chats, contacts and presence](https://docs.d-api.cloud/en/whatsapp/webhooks/chats-contatos-presenca.md) |
| `contacts.update` | Contact updated | [Chats, contacts and presence](https://docs.d-api.cloud/en/whatsapp/webhooks/chats-contatos-presenca.md) |
| `contacts.upsert` | Contact created/updated | [Chats, contacts and presence](https://docs.d-api.cloud/en/whatsapp/webhooks/chats-contatos-presenca.md) |
| `presence` | Presence (online/typing) | [Chats, contacts and presence](https://docs.d-api.cloud/en/whatsapp/webhooks/chats-contatos-presenca.md) |
| `groups_participants.join` | Joined a group | [Groups](https://docs.d-api.cloud/en/whatsapp/webhooks/grupos.md) |
| `groups_participants.leave` | Left a group | [Groups](https://docs.d-api.cloud/en/whatsapp/webhooks/grupos.md) |
| `groups_participants.promote` | Promoted to admin | [Groups](https://docs.d-api.cloud/en/whatsapp/webhooks/grupos.md) |
| `groups_participants.demote` | Demoted from admin | [Groups](https://docs.d-api.cloud/en/whatsapp/webhooks/grupos.md) |
| `group_participants.join-request` | Join request | [Groups](https://docs.d-api.cloud/en/whatsapp/webhooks/grupos.md) |
| `group_participants.join-request.revoked` | Join request revoked | [Groups](https://docs.d-api.cloud/en/whatsapp/webhooks/grupos.md) |
| `group_participants.join-request.approved` | Join request approved | [Groups](https://docs.d-api.cloud/en/whatsapp/webhooks/grupos.md) |
| `labels.edit` | Label created/edited/deleted | [Labels](https://docs.d-api.cloud/en/whatsapp/webhooks/etiquetas.md) |
| `labels.association.chat` | Label applied to/removed from a chat | [Labels](https://docs.d-api.cloud/en/whatsapp/webhooks/etiquetas.md) |
| `labels.association.message` | Label applied to/removed from a message | [Labels](https://docs.d-api.cloud/en/whatsapp/webhooks/etiquetas.md) |
| `call.offer` | Incoming voice call | [Calls (VoIP)](https://docs.d-api.cloud/en/whatsapp/webhooks/chamadas.md) |
| `call.accepted` | Incoming call answered | [Calls (VoIP)](https://docs.d-api.cloud/en/whatsapp/webhooks/chamadas.md) |
| `call.rejected` | Incoming call rejected | [Calls (VoIP)](https://docs.d-api.cloud/en/whatsapp/webhooks/chamadas.md) |
| `call.ringing` | Outgoing call ringing | [Calls (VoIP)](https://docs.d-api.cloud/en/whatsapp/webhooks/chamadas.md) |
| `call.connected` | Outgoing call connected | [Calls (VoIP)](https://docs.d-api.cloud/en/whatsapp/webhooks/chamadas.md) |
| `call.ended` | Outgoing call ended | [Calls (VoIP)](https://docs.d-api.cloud/en/whatsapp/webhooks/chamadas.md) |
| `call.audio` | Call audio (chunks or recording) | [Calls (VoIP)](https://docs.d-api.cloud/en/whatsapp/webhooks/chamadas.md) |
| `history.message.upsert` | History message (RabbitMQ only) | [History and sync](https://docs.d-api.cloud/en/whatsapp/webhooks/historico-e-sincronizacao.md) |
| `history.message.received` | Received message from history (RabbitMQ only) | [History and sync](https://docs.d-api.cloud/en/whatsapp/webhooks/historico-e-sincronizacao.md) |
| `history.messages.sent` | Sent message from history (converted in the webhook) | [History and sync](https://docs.d-api.cloud/en/whatsapp/webhooks/historico-e-sincronizacao.md) |
| `history_sync` | Backfill completion/summary | [History and sync](https://docs.d-api.cloud/en/whatsapp/webhooks/historico-e-sincronizacao.md) |
| `appstate.agent.update` | Linked device/agent updated | [History and sync](https://docs.d-api.cloud/en/whatsapp/webhooks/historico-e-sincronizacao.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.