# message.delivery

Fonte: https://apiwpp.com/docs/webhooks/message-delivery
Seção: Webhooks
Atualizado em: 2026-09-28

Uma mensagem enviada pelo número mudou de status.

`POST` para o `webhookBaseUrl` do projeto.

Uma mensagem mudou de status: `sent`, `delivered`, `read` ou `failed`. Em geral é uma que o número enviou, pela API ou digitada no celular. Chega a todos os projetos, sem configuração.

Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente.

**Um evento por mudança.** Uma mensagem normalmente passa por `sent`, `delivered` e `read`, com um evento para cada status. Cada entrega tem as próprias novas tentativas, então um status pode chegar repetido ou depois do seguinte: guarde o status mais avançado de cada `messageId` e não volte de `read` para `delivered`.

**Correlacionar com o seu envio.** Quando a mensagem saiu por [`POST /connections/{id}/send`](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) com um `clientRef`, ele volta em cada status. O vínculo entre o `messageId` e o `clientRef` vale por 72 horas: um status mais tardio chega com `clientRef: null`, e então você correlaciona pelo `messageId`, que já veio nos status anteriores da mesma mensagem (e em [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing), se o projeto o ativou). Se a consulta a esse vínculo falhar, o evento sai assim mesmo, com `clientRef: null`. Veja [Idempotência](https://apiwpp.com/docs/guias/idempotencia#correlacionar-os-eventos).

**`failed` com `reason: reachout_timelocked`.** O WhatsApp recusou a mensagem como contato frio (erro de confirmação 463, em geral para um contato com quem o número nunca conversou). Ela não foi entregue e não é tentada de novo, e reenviar piora a restrição. Quando a conta entra num bloqueio, a conexão avisa em [`connection.status`](https://apiwpp.com/docs/webhooks/connection-status) com `reason: reachout_timelock`; veja [Bloqueio temporário de novas conversas](https://apiwpp.com/docs/guias/limites-de-envio#bloqueio-temporario-de-novas-conversas). Um `failed` sem `reason` é uma falha que o WhatsApp não explicou.

**Status de mensagens que o número não enviou.** O WhatsApp também manda atualizações de status de mensagens que não saíram deste número, e elas viram `message.delivery` do mesmo jeito, com `clientRef: null`. Compare o `messageId` com os seus envios (o de `message.outgoing` e dos status anteriores) e ignore os ids que você não conhece.

**`failed` não é `message.send_failed`.** Aqui a mensagem saiu e o WhatsApp a recusou. [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed) é o caso em que a apiwpp desistiu de um envio aceito antes de ele sair: não há `messageId`, e o evento só existe para envios com `clientRef`.

**Registro de mensagens.** O status dos envios pela API também é gravado no [registro de mensagens](https://apiwpp.com/docs/api/registros/listar-mensagens).

**Entrega.** Um `POST` com `Content-Type: application/json` ao `webhookBaseUrl` do projeto, feito **pelo menos uma vez**; um projeto inativo não recebe webhooks. Responda `2xx` em até 10 segundos: o corpo da resposta é ignorado, e um redirecionamento (`3xx`) não é seguido e conta como falha. Uma entrega que falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, **6 tentativas** no total, e então fica `dead`. Depois de 5 falhas seguidas, as entregas do projeto ficam em pausa de 30 segundos a 5 minutos, e um evento que passa 24 horas sem ser entregue também fica `dead`. Uma nova tentativa pode chegar depois de eventos mais novos: ordene pelo `timestamp` do envelope. Reenvie as entregas `dead` com [`POST /webhooks/deliveries/{id}/resend`](https://apiwpp.com/docs/api/registros/reenviar-entrega) ou [`POST /webhooks/deliveries/resend-dead`](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas).

**Assinatura.** `X-Webhook-Token` vem sempre, com o `webhookToken` do projeto, junto com os `webhookHeaders` personalizados. Com um `webhookSecret`, cada tentativa também traz `X-Sales-Timestamp` (segundos unix da tentativa) e `X-Sales-Signature`: calcule `"sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + corpo))` sobre os bytes do corpo exatamente como chegaram, compare em tempo constante e rejeite um `X-Sales-Timestamp` a mais de 300 segundos do seu relógio. Veja [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).

## Cabeçalhos da entrega

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `X-Webhook-Token` | `string` | sim | O `webhookToken` do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com [`PATCH /tenants/{id}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto). Os `webhookHeaders` personalizados do projeto também são enviados. |
| `X-Sales-Timestamp` | `string` | não | Só quando o projeto tem um webhookSecret: segundos unix desta tentativa de entrega (as novas tentativas são assinadas de novo). Rejeite um que esteja a mais de 300 s do seu relógio. (formato `^\d+$`) |
| `X-Sales-Signature` | `string` | não | Só quando o projeto tem um webhookSecret: "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + rawBody)). Calcule sobre os bytes do corpo exatamente como recebidos, nunca sobre um objeto serializado de novo, e compare em tempo constante. (formato `^sha256=[0-9a-f]{64}$`) |

## Envelope

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `type` | `string` | sim | O tipo do evento, que decide o formato de `data`. Ignore os tipos que você não conhece: a lista de eventos pode crescer. (sempre "message.delivery") |
| `connectionId` | `string · uuid` | sim | O id (UUID) da conexão, ou seja, do número, que gerou o evento. |
| `tenantId` | `string · uuid` | sim | O id (UUID) do projeto dono da conexão. |
| `externalId` | `string \| null` | sim | O `externalId` que você informou ao criar a conexão, para ligá-la a um registro seu. `null` quando a conexão foi criada sem ele. |
| `timestamp` | `string · date-time` | sim | Quando o evento foi gerado, em ISO 8601 (UTC). É o mesmo em todas as tentativas de entrega; o momento de cada tentativa vem no cabeçalho `X-Sales-Timestamp`. |

## Campos de `data`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `messageId` | `string` | sim | O id da mensagem no WhatsApp: o mesmo de `message.outgoing` e dos status anteriores desta mensagem. Guarde o status mais avançado por esta chave. |
| `status` | `string` | sim | `sent`: o servidor do WhatsApp recebeu a mensagem. `delivered`: ela chegou ao aparelho do destinatário. `read`: foi lida (ou, numa mensagem de voz, ouvida). `failed`: não foi entregue. Valores: `"sent"`, `"delivered"`, `"read"`, `"failed"`. |
| `recipient` | `string` | sim | Campo legado: o JID sem `@s.whatsapp.net` (um LID passa inteiro). Prefira `jid` e `phone`. |
| `jid` | `string` | sim | JID bruto da outra pessoa (`…@s.whatsapp.net` ou `…@lid`). Sempre presente. |
| `phone` | `string \| null` | sim | Telefone da outra pessoa em E.164 (por exemplo, `+5511999999999`). `null` quando a conversa usa um LID que a apiwpp não conseguiu resolver, ou numa conversa em grupo; o evento nunca é descartado por isso. (formato `^\+[1-9]\d{7,14}$`) |
| `clientRef` | `string \| null` | sim | O `clientRef` passado a `POST /connections/{id}/send` para esta mensagem. `null` quando o envio não tinha um, quando a mensagem não saiu pela API ou depois de 72 horas do envio. |
| `reason` | `string` | não | Só com `status: failed`, quando o WhatsApp disse o motivo; ausente nos outros casos. `reachout_timelocked`: o WhatsApp recusou a mensagem como contato frio (erro 463); ela não foi entregue nem é tentada de novo. Valores: `"reachout_timelocked"`. |

## Exemplo

```json
{
  "type": "message.delivery",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:00.000Z",
  "data": {
    "messageId": "3EB0C767D26A1D8A3F52",
    "status": "delivered",
    "recipient": "5511988887777",
    "clientRef": "crm-msg-1",
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777"
  }
}
```

Guia: [Idempotência](https://apiwpp.com/docs/guias/idempotencia).
