# Webhooks: visão geral

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

O envelope comum a todos os eventos, os cabeçalhos de cada entrega, as regras de entrega e o catálogo dos 11 eventos que a apiwpp envia.

Tudo o que acontece com um número chega ao seu sistema como um **evento**: um `POST` em JSON ao `webhookBaseUrl` do projeto. Esta página é o mapa: o formato comum, os cabeçalhos, as regras de entrega e a lista de eventos, cada um com a sua página de campos. Para configurar o endpoint, verificar a assinatura e reenviar entregas, siga o guia [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).

## O envelope

Todo evento chega no mesmo envelope. Só `data` muda conforme o `type`:

**message.incoming**

```json
{
  "type": "message.incoming",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-25T12:00:02.000Z",
  "data": {
    "from": "5511988887777@s.whatsapp.net",
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777",
    "resolvedPhone": "5511988887777",
    "to": "5511900000001:7@s.whatsapp.net",
    "body": "Olá! Tem horário amanhã às 10h?",
    "timestamp": 1790251200,
    "raw": { "key": { "remoteJid": "5511988887777@s.whatsapp.net", "fromMe": false, "id": "IN-TEXT-1" } }
  }
}
```

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `type` | string | O tipo do evento, um dos listados em [Os eventos](#os-eventos) |
| `connectionId` | string (uuid) | A conexão (o número) que gerou o evento |
| `tenantId` | string (uuid) | O projeto que recebe o evento |
| `externalId` | string ou `null` | O seu identificador da conexão, dado na criação dela; `null` quando não há |
| `timestamp` | string (ISO 8601) | Quando o evento aconteceu |
| `data` | objeto | Os campos do evento, descritos na página de cada `type` |

Todos os campos do envelope vêm sempre (`externalId` pode ser `null`). O `timestamp` do envelope é uma data ISO; dentro de `data`, os campos `timestamp` das mensagens são **segundos Unix**. No evento de teste [`ping`](https://apiwpp.com/docs/webhooks/ping), `connectionId`, `tenantId` e `externalId` vêm `null`.

## Os cabeçalhos

| Cabeçalho | Quando | Conteúdo |
| --- | --- | --- |
| `Content-Type` | Sempre | `application/json` |
| `X-Webhook-Token` | Sempre | O `webhookToken` do projeto |
| `X-Sales-Timestamp` | Com `webhookSecret` | Segundos Unix do momento da tentativa; cada nova tentativa é assinada de novo |
| `X-Sales-Signature` | Com `webhookSecret` | `sha256=` + hex(HMAC-SHA256(`webhookSecret`, `timestamp` + `"."` + corpo bruto)) |
| Os seus cabeçalhos | Com `webhookHeaders` | Os cabeçalhos extras configurados no projeto |

Os cabeçalhos de `webhookHeaders` podem substituir `Content-Type` e `X-Webhook-Token`, mas nunca `X-Sales-Timestamp` e `X-Sales-Signature`, que são definidos por último. Verifique a assinatura sobre os bytes do corpo como chegaram e recuse um `X-Sales-Timestamp` a mais de 300 segundos do seu relógio: o passo a passo, com código em Node.js, PHP e Python, está em [Verifique a assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura#verifique-a-assinatura). A lista de todos os cabeçalhos da API está em [Cabeçalhos](https://apiwpp.com/docs/referencia/cabecalhos).

## A entrega

- **Pelo menos uma vez.** Novas tentativas e reconexões podem entregar o mesmo evento de novo. Aplique cada evento de forma idempotente, por uma chave do próprio evento: `data.messageId` nos eventos que a trazem (com `data.status` nos recibos e `data.emoji` nas reações); em `message.incoming`, que não tem `messageId`, `data.jid` mais `data.raw.key.id`; em `message.send_failed`, `data.jobId` (ou o seu `data.clientRef`). Um evento emitido de novo numa reconexão ganha outro `timestamp` no envelope, então o corpo inteiro só serve de chave para as novas tentativas de uma mesma entrega, que repetem o corpo byte a byte.
- **Sem ordem garantida.** Uma entrega em nova tentativa pode chegar depois de eventos mais novos. Ordene pelo `timestamp` do envelope.
- **Responda `2xx` em até 10 segundos.** Qualquer outra resposta, um redirecionamento, um erro de rede ou o tempo esgotado conta como falha. São **6 tentativas** no total; um evento que não foi entregue em 24 horas fica `dead` e pode ser reenviado pelo [registro de entregas](https://apiwpp.com/docs/guias/webhooks-e-assinatura#registro-e-reenvio). Os números estão em [Limites](https://apiwpp.com/docs/referencia/limites#webhooks).
- **Projeto inativo não recebe.** Um projeto desativado não recebe webhooks, e desativá-lo fecha as conexões dele sem enviar nenhum evento.
- **O contrato só cresce.** Ignore os tipos de evento que você não conhece e os campos que não usa: tipos e campos novos podem aparecer, mas nenhum é renomeado ou removido.

## Os eventos

| `type` | Quando chega | Campos principais de `data` |
| --- | --- | --- |
| [`connection.status`](https://apiwpp.com/docs/webhooks/connection-status) | A conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazer | `status`, `phoneNumber`, `reason`, `willReconnect`, `statusCode`, `reachoutTimelock` |
| [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming) | Alguém escreveu para o número (texto, mídia, localização), numa conversa individual ou num grupo | `from`, `jid`, `phone`, `resolvedPhone`, `to`, `body`, `timestamp`, `media`, `location`, `raw` |
| [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing) | O número enviou uma mensagem numa conversa individual, pela API ou pelo celular; só com `emitOutgoing: true` no projeto | `messageId`, `origin`, `clientRef`, `to`, `toE164`, `jid`, `phone`, `body`, `timestamp`, `mediaType` |
| [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery) | Uma mensagem mudou de status: `sent`, `delivered`, `read` ou `failed`. Em geral uma que o número enviou, mas pode vir de uma que ele não enviou (com `clientRef: null`): ignore os `messageId` que você não conhece | `messageId`, `status`, `recipient`, `clientRef`, `jid`, `phone`, `reason` |
| [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed) | Um envio aceito com `clientRef` não vai acontecer | `clientRef`, `jobId`, `messageId`, `to`, `reason`, `attempts`, `jid`, `phone` |
| [`message.reaction`](https://apiwpp.com/docs/webhooks/message-reaction) | Alguém reagiu a uma mensagem, ou removeu a reação (`emoji` vazio) | `messageId`, `from`, `emoji`, `jid`, `phone` |
| [`contact.resolved`](https://apiwpp.com/docs/webhooks/contact-resolved) | Um remetente que chegou só com LID agora tem telefone | `lid`, `jid`, `phone`, `firstSeenAt`, `messageCount`, `source` |
| [`group.joined`](https://apiwpp.com/docs/webhooks/group-joined) | O número entrou num grupo; também uma vez por grupo quando a conexão abre pela primeira vez no processo | `groupId`, `groupName`, `participantCount` |
| [`group.left`](https://apiwpp.com/docs/webhooks/group-left) | O número foi removido de um grupo | `groupId`, `reason` |
| [`group.updated`](https://apiwpp.com/docs/webhooks/group-updated) | Um grupo do número mudou (o nome) | `groupId`, `groupName` |
| [`ping`](https://apiwpp.com/docs/webhooks/ping) | Só no teste do endpoint com [`POST /tenants/webhook-test`](https://apiwpp.com/docs/api/projetos/testar-webhook) | `message` |

Os dez primeiros estão na seção `webhooks` da especificação OpenAPI, que pode ser baixada na [página inicial da documentação](https://apiwpp.com/docs). O `ping` não faz parte dela.

### Os campos de endereço

Os eventos de mensagem identificam a outra pessoa da conversa da mesma forma:

| Campo | Descrição |
| --- | --- |
| `jid` | O JID do WhatsApp da conversa (`…@s.whatsapp.net`, `…@lid` ou, em grupos, `…@g.us`). Vem sempre |
| `phone` | O telefone em E.164 (`+5511988887777`), ou `null` num grupo ou quando o contato chegou só com um LID que ainda não foi resolvido |
| `clientRef` | Em `message.outgoing`, `message.delivery` e `message.send_failed`: o `clientRef` do envio, ou `null` quando não houve um |

Um evento nunca é descartado por não ter telefone. Quando `phone` é `null` por causa de um LID, o telefone chega depois em [`contact.resolved`](https://apiwpp.com/docs/webhooks/contact-resolved): veja [LID e contact.resolved](https://apiwpp.com/docs/guias/lid-e-contact-resolved).

## Um receptor mínimo

Um endpoint que confere a assinatura, responde logo, descarta repetições e despacha pelo `type`:

**Node.js**

```js
import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET não está definido')

function isSigned(rawBody, timestamp, signature) {
  if (!/^\d+$/.test(timestamp ?? '') || !signature) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const mac = createHmac('sha256', SECRET).update(`${timestamp}.`).update(rawBody).digest('hex')
  const expected = Buffer.from(`sha256=${mac}`)
  const received = Buffer.from(signature)
  return expected.length === received.length && timingSafeEqual(expected, received)
}

// Em produção, guarde as chaves já vistas num banco ou no Redis, com prazo
const seen = new Set()

function dedupeKey(event, rawBody) {
  const { type, data } = event
  if (type === 'message.incoming' && data?.raw?.key?.id) return `${type}:${data.jid}:${data.raw.key.id}`
  if (type === 'message.send_failed') return `${type}:${data.jobId}`
  if (data?.messageId) return `${type}:${data.messageId}:${data.status ?? data.emoji ?? ''}`
  // Sem chave no evento: o corpo, que só se repete nas novas tentativas da mesma entrega
  return createHash('sha256').update(rawBody).digest('hex')
}

const handlers = {
  'connection.status': (e) => console.log('conexão', e.connectionId, e.data.status, e.data.reason ?? ''),
  'message.incoming': (e) => console.log('mensagem de', e.data.phone ?? e.data.jid, e.data.body),
  'message.delivery': (e) => console.log('status', e.data.clientRef, e.data.status),
  'message.send_failed': (e) => console.log('não enviado', e.data.clientRef, e.data.reason),
  'contact.resolved': (e) => console.log('reatribuir', e.data.lid, 'para', e.data.phone),
}

const app = express()

app.post('/whatsapp/events', express.raw({ type: 'application/json' }), (req, res) => {
  if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
    return res.sendStatus(401)
  }
  res.sendStatus(204) // responda antes de processar

  const event = JSON.parse(req.body.toString('utf8'))
  const key = dedupeKey(event, req.body)
  if (seen.has(key)) return
  seen.add(key)

  // Tipos desconhecidos são ignorados: o contrato pode ganhar eventos novos
  handlers[event.type]?.(event)
})

app.listen(3000)
```

Para ver uma entrega de verdade chegando, dispare um `ping` assinado com o segredo guardado do projeto:

**Testar o endpoint**

```bash
curl -s -X POST https://api.apiwpp.com/tenants/webhook-test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookBaseUrl": "https://crm.example.com/whatsapp/events", "tenantId": "'$TENANT_ID'"}'
```

Resposta `200`

```json
{ "ok": true, "status": 204, "latencyMs": 184, "error": null }
```

> **Escopo**
>
> O teste pede uma chave com `webhooks:write`. O `webhookBaseUrl` do exemplo precisa ser a URL salva do projeto para o token e os cabeçalhos guardados irem junto; para outra URL, envie também `webhookToken`.

## Próximos passos

- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): configurar o endpoint, verificar a assinatura, novas tentativas e reenvio.
- [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming): os campos de uma mensagem recebida, com mídia e localização.
- [Idempotência](https://apiwpp.com/docs/guias/idempotencia): ligar `message.delivery` e `message.send_failed` aos seus envios pelo `clientRef`.
- [LID e contact.resolved](https://apiwpp.com/docs/guias/lid-e-contact-resolved): o que fazer quando `phone` vem `null`.
