Webhooks: visão geral
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.
O envelope
Todo evento chega no mesmo envelope. Só data muda conforme o type:
{
"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": "[email protected]",
"jid": "[email protected]",
"phone": "+5511988887777",
"resolvedPhone": "5511988887777",
"to": "5511900000001:[email protected]",
"body": "Olá! Tem horário amanhã às 10h?",
"timestamp": 1790251200,
"raw": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "IN-TEXT-1" } }
}
}| Campo | Tipo | Descrição |
|---|---|---|
type | string | O tipo do evento, um dos listados em 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, 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. A lista de todos os cabeçalhos da API está em Cabeçalhos.
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.messageIdnos eventos que a trazem (comdata.statusnos recibos edata.emojinas reações); emmessage.incoming, que não temmessageId,data.jidmaisdata.raw.key.id; emmessage.send_failed,data.jobId(ou o seudata.clientRef). Um evento emitido de novo numa reconexão ganha outrotimestampno 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
timestampdo envelope. - Responda
2xxem 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 ficadeade pode ser reenviado pelo registro de entregas. Os números estão em Limites. - 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 | A conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazer | status, phoneNumber, reason, willReconnect, statusCode, reachoutTimelock |
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 | 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 | 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 | Um envio aceito com clientRef não vai acontecer | clientRef, jobId, messageId, to, reason, attempts, jid, phone |
message.reaction | Alguém reagiu a uma mensagem, ou removeu a reação (emoji vazio) | messageId, from, emoji, jid, phone |
contact.resolved | Um remetente que chegou só com LID agora tem telefone | lid, jid, phone, firstSeenAt, messageCount, source |
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 | O número foi removido de um grupo | groupId, reason |
group.updated | Um grupo do número mudou (o nome) | groupId, groupName |
ping | Só no teste do endpoint com POST /tenants/webhook-test | 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. 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: veja LID e contact.resolved.
Um receptor mínimo
Um endpoint que confere a assinatura, responde logo, descarta repetições e despacha pelo type:
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:
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'"}'{ "ok": true, "status": 204, "latencyMs": 184, "error": null }Próximos passos
- Webhooks e assinatura: configurar o endpoint, verificar a assinatura, novas tentativas e reenvio.
message.incoming: os campos de uma mensagem recebida, com mídia e localização.- Idempotência: ligar
message.deliveryemessage.send_failedaos seus envios peloclientRef. - LID e contact.resolved: o que fazer quando
phonevemnull.