Webhooks do WhatsApp: como receber e validar mensagens no seu sistema
Configure o endereço do webhook, verifique a assinatura HMAC em Node.js e PHP e processe os eventos do WhatsApp sem duplicar nada.
Enviar uma mensagem pela API é a parte fácil. O trabalho de verdade começa depois: o cliente respondeu, a mensagem foi lida, o número caiu, um envio não vai acontecer. Se o seu sistema precisa consultar a API de minuto em minuto para descobrir isso, ele chega atrasado e gasta requisições à toa.
Webhook resolve o problema pelo outro lado. Em vez de você perguntar, a apiwpp avisa: a cada evento do número, ela faz um POST para um endereço do seu sistema com um JSON descrevendo o que aconteceu. Se o termo é novo para você, o glossário explica o que é webhook em poucas linhas.
Este tutorial cobre o caminho completo: o formato dos eventos, como configurar o endereço e o segredo, como verificar a assinatura HMAC em Node.js e em PHP, como responder rápido e como processar cada evento uma única vez, mesmo quando ele chega duas vezes.
O envelope: todo evento chega no mesmo formato
Todos os eventos usam o mesmo envelope. Só o conteúdo de data muda conforme o type (aqui, uma mensagem recebida com parte dos campos):
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "loja-42",
"timestamp": "2026-09-19T12:00:00.000Z",
"data": {
"jid": "[email protected]",
"phone": "+5511988887777",
"body": "Olá! Meu pedido já saiu?",
"timestamp": 1789819200
}
}
Cada campo tem um papel:
typediz o que aconteceu e decide como o seu código trata o evento.connectionIdidentifica o número (a conexão) de onde o evento veio. Um projeto com vários números recebe todos no mesmo endereço, e é esse campo que separa um do outro.tenantIdé o projeto.externalIdé o identificador que você mesmo deu ao projeto, útil para mapear o evento para um cliente do seu sistema sem consultar nada.timestampé o momento do evento, em ISO 8601.datatraz os detalhes. Nos eventos de mensagem,jidé o endereço interno do WhatsApp ephoneé o telefone em E.164, quando é possível resolvê-lo.
Os tipos de evento
type | Quando chega |
|---|---|
connection.status | A conexão abriu ou fechou, com o motivo em reason e se vai reconectar sozinha em willReconnect |
message.incoming | Alguém escreveu para o número: texto, mídia ou localização, em conversa individual ou em grupo |
message.outgoing | O número enviou uma mensagem, pela API ou digitada no celular. Opcional, ligado por projeto |
message.delivery | Uma mensagem enviada mudou de status: sent, delivered, read ou failed |
message.send_failed | Um envio feito com clientRef não vai acontecer, com o motivo |
message.reaction | Alguém reagiu a uma mensagem, ou removeu a reação |
contact.resolved | Um remetente que chegou só com LID agora tem telefone |
group.joined, group.left, group.updated | O número entrou num grupo, saiu dele, ou o grupo mudou |
Dois detalhes evitam dor de cabeça. Primeiro, mídia recebida chega em data.media.url como um link assinado e temporário: baixe o arquivo quando o evento chegar, em vez de guardar o link, e não o registre em log. Segundo, um evento pode chegar com phone: null quando o remetente é identificado só por um LID; o evento contact.resolved avisa quando o telefone aparecer. O glossário de LID explica o porquê.
A lista completa, com o schema de cada evento, está na página de webhooks assinados e na documentação da API.
Configure o endereço e o segredo
Cada projeto tem um endereço de webhook, o webhookBaseUrl. Ele precisa ser uma URL https pública que responde direto: redirecionamentos não são seguidos. Todos os números do projeto enviam os eventos para esse mesmo endereço.
Em seguida, defina um segredo de assinatura. Com ele, cada entrega passa a trazer uma assinatura HMAC que prova que o evento veio da apiwpp e não foi alterado no caminho. Gere um valor aleatório e guarde no cofre de segredos do servidor que recebe os webhooks antes de enviá-lo, porque a API nunca o devolve:
WEBHOOK_SECRET=$(openssl rand -hex 32)
curl -s -X PATCH https://api.apiwpp.com/tenants/$TENANT_ID \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d "{\"webhookSecret\": \"$WEBHOOK_SECRET\"}"
A resposta traz "hasWebhookSecret": true, nunca o segredo. Se o valor se perder, defina um novo do mesmo jeito. A mesma rota altera o webhookBaseUrl e liga o evento message.outgoing com "emitOutgoing": true. A chave usada precisa do escopo webhooks:write.
Para testar na sua máquina, exponha a porta local com um túnel https (ngrok, cloudflared ou similar) e use essa URL como endereço do projeto enquanto desenvolve.
Verifique a assinatura HMAC
Com o segredo definido, cada tentativa de entrega traz três cabeçalhos:
| Cabeçalho | Conteúdo |
|---|---|
X-Sales-Timestamp | Segundos unix do momento da tentativa. Cada nova tentativa é assinada de novo |
X-Sales-Signature | sha256= seguido do hex do HMAC-SHA256 de timestamp + "." + corpo bruto, com o segredo como chave |
X-Webhook-Token | O token do projeto, enviado sempre, com ou sem assinatura |
A verificação tem três regras, e todas importam:
- Use o corpo bruto. Calcule o HMAC sobre os bytes exatamente como chegaram. Se o seu framework já converteu o JSON em objeto, serializar de novo muda espaços e ordem, e a assinatura não confere.
- Recuse timestamps velhos. Um
X-Sales-Timestampa mais de 300 segundos do seu relógio é recusado. Isso impede que alguém capture uma entrega e a repita depois. - Compare em tempo constante. Uma comparação comum de strings para no primeiro caractere diferente, e o tempo de resposta vaza informação. Use
timingSafeEqualno Node.js ehash_equalsno PHP.
Se o conceito de HMAC for novo, vale ler a definição antes de seguir.
Node.js com Express
A rota usa express.raw para receber o corpo como Buffer, sem conversão:
import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'
const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET
// Sem segredo não há o que verificar: o servidor não sobe
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET não está definido')
const TOLERANCE_SECONDS = 300
function isSigned(rawBody, timestamp, signature) {
if (!/^\d+$/.test(timestamp ?? '') || !signature) return false
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) 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)
}
const app = express()
app.post('/whatsapp/events', express.raw({ type: 'application/json' }), async (req, res) => {
if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
return res.sendStatus(401)
}
const event = JSON.parse(req.body.toString('utf8'))
await queue.add('whatsapp-event', { event, raw: req.body.toString('utf8') }) // processe fora da requisição
res.sendStatus(204)
})
app.listen(3000)
O queue é a fila que você já usa (BullMQ, SQS, uma tabela no banco). O ponto é não fazer o trabalho pesado dentro da requisição. O mesmo padrão, com o envio de mensagens junto, está na página de integração com Node.js.
PHP puro
Em PHP, o corpo bruto vem de php://input:
<?php
$secret = getenv('WHATSAPP_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') {
// Sem segredo não há o que verificar: recuse tudo até configurá-lo
http_response_code(500);
exit;
}
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_SALES_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SALES_SIGNATURE'] ?? '';
$fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!$fresh || !hash_equals($expected, $signature)) {
http_response_code(401);
exit;
}
$event = json_decode($rawBody, true);
// Enfileire $event e processe depois
http_response_code(204);
No Laravel, o corpo bruto é $request->getContent(), os cabeçalhos vêm de $request->header(...) e o segredo deve vir de config(...), nunca de getenv(): com php artisan config:cache, o .env deixa de ser lido e getenv() devolve false. Lembre também de tirar a rota do webhook da proteção CSRF. O passo a passo com middleware e Jobs está no tutorial de WhatsApp com PHP e Laravel.
O erro que mais se repete: segredo vazio
Um HMAC calculado com chave vazia pode ser reproduzido por qualquer pessoa. Se a variável de ambiente não chegou ao processo (deploy sem a variável, cache de configuração, typo no nome), o verificador precisa recusar tudo, como nos dois exemplos acima, e não comparar assinaturas com uma chave vazia.
Sem webhookSecret no projeto as entregas não são assinadas. Nesse caso, confira pelo menos o X-Webhook-Token, também em tempo constante. Mas prefira sempre o segredo.
Responda 2xx rápido e processe depois
A regra de ouro de qualquer webhook: responda 2xx em até 10 segundos e deixe o trabalho para depois. O corpo da sua resposta é ignorado. Qualquer outra coisa conta como falha: um 3xx, um 4xx, um 5xx, um erro de rede ou o tempo esgotado.
Na prática, a rota do webhook faz só três coisas: verifica a assinatura, grava o evento numa fila ou tabela e responde 204. Consultar o CRM, chamar outra API, gerar um PDF ou mandar uma resposta automática ficam para um worker.
Duas armadilhas comuns:
- Tipos desconhecidos. Ignore os tipos de evento que você não trata e os campos que não usa, mas responda 2xx mesmo assim. O contrato só cresce: tipos e campos novos podem aparecer, e nada é renomeado ou removido. Um
400para um tipo novo vira uma sequência de novas tentativas para nada. - Erro no processamento. Se o seu worker falhar, isso é problema da sua fila, não da entrega. Como o evento já foi aceito com
204, trate o erro com as novas tentativas da sua própria fila.
Processe cada evento uma única vez
A entrega é pelo menos uma vez (at-least-once). O mesmo evento pode chegar de novo: uma resposta que se perdeu na rede, um tempo esgotado do seu lado ou um reenvio feito por você no painel. O seu código precisa aceitar a repetição sem efeito duplicado, ou seja, ser idempotente.
O jeito mais simples é derivar uma chave de cada evento e guardá-la numa tabela com restrição de unicidade. Se a chave já existe, o evento já foi processado:
import { createHash } from 'node:crypto'
function eventKey(event, raw) {
const d = event.data ?? {}
switch (event.type) {
case 'message.incoming':
if (d.raw?.key?.id) return `in:${event.connectionId}:${d.raw.key.id}`
break
case 'message.outgoing':
return `out:${event.connectionId}:${d.messageId}`
case 'message.delivery':
return `dlv:${event.connectionId}:${d.messageId}:${d.status}`
case 'message.send_failed':
return `fail:${event.connectionId}:${d.jobId}`
}
// Os demais tipos: o mesmo evento reenviado tem o mesmo corpo
return `body:${createHash('sha256').update(raw).digest('hex')}`
}
CREATE TABLE whatsapp_events (
event_key TEXT PRIMARY KEY,
received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- No worker: se nenhuma linha foi inserida, o evento já foi processado
INSERT INTO whatsapp_events (event_key) VALUES ($1) ON CONFLICT DO NOTHING;
Algumas observações sobre essa chave:
- Em
message.delivery, o mesmomessageIdchega várias vezes, uma para cada status. Por isso o status entra na chave. Trate o status como uma progressão: uma mensagem já marcada comoreadno seu sistema não deve voltar paradelivered. - Em
message.incoming, o identificador da mensagem no WhatsApp está emdata.raw.key.id. O camporawsegue o formato do WhatsApp, não o contrato da API: leia dele só o que os outros campos não trazem. - Para ligar os eventos aos seus registros, use o
clientRefque você enviou no/send. Ele volta emmessage.outgoing,message.deliveryemessage.send_failed. Depois de 72 horas, um status tardio pode chegar comclientRef: null, e aí você correlaciona pelomessageId.
O outro lado da mesma moeda é o envio: repetir um POST /connections/{id}/send com o mesmo clientRef devolve o job original com "duplicate": true em vez de mandar a mensagem de novo. O guia sobre mensagens duplicadas junta as duas pontas.
Novas tentativas, registro e reenvio
Quando uma entrega falha, a apiwpp tenta de novo depois de cerca de 2, 4, 8, 16 e 32 segundos: 6 tentativas no total. Depois disso, a entrega fica no estado dead. Se o seu endpoint falha em sequência, as entregas do projeto são pausadas por 30 segundos a 5 minutos e retomadas depois de uma entrega de teste; os eventos esperam na fila. Um evento que passa 24 horas sem ser entregue também fica dead.
Para saber o que aconteceu, cada entrega fica registrada com o estado (delivered, retry ou dead), o status HTTP que o seu servidor respondeu, o erro, a latência e o corpo enviado. O registro aparece no painel e na API:
curl -s "https://api.apiwpp.com/webhooks/deliveries?state=dead" \
-H "Authorization: Bearer $APIWPP_KEY"
Quando o seu endpoint voltar, você reenvia o que ficou para trás:
POST /webhooks/deliveries/{id}/resendreenvia uma entrega, na hora e com novas tentativas;POST /webhooks/deliveries/resend-deadreenvia todas as entregasdeaddos seus projetos, até 1000 por chamada.
É aqui que a idempotência paga a conta: depois de um incidente, você reenvia tudo sem medo, e os eventos que já tinham sido processados são descartados pela chave. Os registros ficam guardados por alguns dias (7 por padrão), então confira as entregas dead logo depois de cada incidente.
Um roteador de eventos que aguenta o tempo
Com a entrega segura e sem duplicidade, o que sobra é a regra de negócio. Um roteador simples no worker resolve a maioria dos casos:
async function handle(event) {
switch (event.type) {
case 'message.incoming':
return tickets.addMessage(event.externalId, event.data)
case 'message.delivery':
return messages.updateStatus(event.data.clientRef ?? event.data.messageId, event.data.status)
case 'message.send_failed':
return messages.markFailed(event.data.clientRef, event.data.reason)
case 'connection.status':
if (event.data.status === 'close' && event.data.willReconnect === false) {
return alerts.notify(`Número ${event.connectionId} desconectado: ${event.data.reason}`)
}
return
default:
return // tipo que você não trata: ignore
}
}
Repare no connection.status: avise alguém na hora quando o fechamento vem com willReconnect: false (por exemplo, logged_out, que exige um QR code novo). Com willReconnect: true, a apiwpp reconecta sozinha; só avise se o open não chegar dentro do prazo que você definir. Esse evento também informa o motivo reachout_timelock, um bloqueio temporário de novas conversas, assunto do guia sobre como evitar o bloqueio do número.
Se você usa ferramentas de automação, o mesmo envelope funciona num nó Webhook do n8n. E se o seu produto é um SaaS em que cada cliente conecta o próprio número, o externalId é o que liga cada evento ao cliente certo, como mostra o guia de WhatsApp dentro do seu SaaS.
Como começar hoje
- Crie uma rota https pública no seu sistema que leia o corpo bruto e responda
204. - Gere o segredo com
openssl rand -hex 32, guarde no cofre do servidor e defina no projeto comPATCH /tenants/{id}. - Implemente a verificação da assinatura com tolerância de 300 segundos e comparação em tempo constante, recusando tudo se o segredo estiver vazio.
- Grave cada evento numa fila e processe num worker, com uma chave de idempotência e uma tabela com restrição de unicidade.
- Ignore tipos de evento desconhecidos, sempre respondendo
2xx. - Crie sua conta na apiwpp, conecte um número e mande uma mensagem para ele: o primeiro
message.incomingchega no seu endereço em seguida. Os planos por número estão em preços.
Perguntas frequentes
Por que o mesmo evento chegou duas vezes no meu webhook?
Porque a entrega é pelo menos uma vez: se a resposta do seu servidor se perde, demora mais de 10 segundos ou não é 2xx, a apiwpp tenta de novo. Reenvios feitos no painel também repetem eventos. Por isso cada evento deve ser processado de forma idempotente, com uma chave como o messageId somado ao tipo e ao status.
A assinatura não confere. O que pode estar errado?
Quase sempre é o corpo: o HMAC precisa ser calculado sobre os bytes exatamente como chegaram, antes de qualquer conversão de JSON. Confira também se a mensagem assinada é o timestamp, um ponto e o corpo, se o segredo é o mesmo definido no projeto e se o relógio do servidor está certo, já que timestamps a mais de 300 segundos são recusados.
Quanto tempo tenho para responder a um webhook?
Até 10 segundos, e a resposta precisa ser 2xx. O corpo da resposta é ignorado. Grave o evento numa fila, responda na hora e faça o processamento pesado num worker.
O que acontece se o meu servidor ficar fora do ar?
Cada entrega é tentada 6 vezes, com intervalos de cerca de 2 a 32 segundos, e as entregas do projeto são pausadas por alguns minutos se o endpoint falha em sequência. O que não for entregue fica no estado dead. Quando o servidor voltar, reenvie uma entrega ou todas as dead pelo painel ou pela API.
Posso receber as mensagens que eu mesmo envio?
Sim, com o evento message.outgoing, que é opcional e ligado por projeto com emitOutgoing: true. Ele informa a origem de cada mensagem: API, para o que saiu pela integração, ou PHONE, para o que foi digitado no celular. É útil para espelhar no seu sistema a conversa completa.
Preciso de um endereço de webhook para cada número?
Não. O endereço é do projeto, e todos os números do projeto enviam os eventos para ele. O campo connectionId diz de qual número veio cada evento. Se você atende vários clientes, use um projeto por cliente, cada um com o próprio endereço e segredo.
Leia também: