Webhook WhatsApp API para receber mensagens e eventos
Como usar webhook WhatsApp API e fila RabbitMQ para receber mensagens, status e eventos de conexão no seu SaaS, com retentativa e deduplicação.
Time D-API. Atualizado em .9 min de leitura.
Um webhook WhatsApp API é o que permite ao seu SaaS acompanhar cada conversa do cliente final enquanto ela acontece. Sem ele, você não sabe quando o cliente final respondeu, quando a mensagem foi lida ou quando o número do seu cliente caiu. Com ele, cada um desses fatos vira um evento HTTP no seu backend, em tempo real, pronto para alimentar inbox, CRM, chatbot ou agente de IA.
Este artigo mostra como receber esses eventos com segurança e sem perder nada: o envelope que a D-API envia, os eventos disponíveis, a política de entrega (retentativas, timeout, falhas permanentes, circuit breaker e deduplicação) e a alternativa de consumir tudo por uma fila RabbitMQ por sessão. Tudo o que está aqui vem da documentação técnica e vale para as mais de 1.300 conexões ativas que a D-API opera hoje.
Um envelope único para todos os eventos
A vantagem para quem integra é escrever um único parser. Mensagem, status, conexão, grupo ou chamada, todo webhook chega com o mesmo formato, e só o conteúdo de data muda:
{
"event": "messages.received",
"sessionId": "my-session",
"data": { "...": "específico do evento" },
"timestamp": "2026-01-24T22:51:32.601Z",
"traceId": "c17dee440402792623e3ad6d925cb000"
}
O event diz o que aconteceu e o sessionId diz em qual sessão. Num SaaS com vários clientes, o sessionId é a chave que leva o evento ao tenant certo, como explicamos em API WhatsApp multi-tenant. O timestamp vem em ISO 8601 (UTC) e o traceId serve para rastrear o evento de ponta a ponta, em log e em conversa com o suporte.
Os headers são fixos: Content-Type: application/json e User-Agent: Deliverify-Webhook/1.0. A D-API não envia assinatura HMAC. Para restringir a origem, use uma URL secreta com token no path e confira se o sessionId recebido é um que você espera.
Como fica uma mensagem recebida
Este é um messages.received real de texto, como aparece na documentação:
{
"event": "messages.received",
"sessionId": "my-session",
"timestamp": "2026-01-24T22:51:32.601Z",
"traceId": "c17dee440402792623e3ad6d925cb000",
"data": {
"id": "AC9831DDA691236BA3CE4909A187B703",
"type": "text",
"message": "Olá!",
"timestamp": 1769295092000,
"fromMe": false,
"is_group": false,
"group_name": "",
"from": {
"jid": "[email protected]",
"lid": "163896103039140@lid",
"name": "João"
},
"from_name": "João",
"to": { "jid": "[email protected]", "name": "Minha Empresa" },
"media_url": null
}
}
O remetente vem como JID e também com o LID, o identificador interno do WhatsApp. Em mensagens de mídia, media_url aponta para o arquivo já armazenado e media_data traz mimetype, tamanho, legenda e duração. O campo type cobre texto, imagem, vídeo, áudio, documento, figurinha, contato, localização, reação, edição, voto em enquete e respostas de mensagens interativas, como list_response e template_button_reply. Se o seu produto usa botões e listas, o artigo sobre botões e listas pela API mostra o ciclo completo de envio e resposta.
Os eventos que importam para um SaaS
Você não precisa assinar tudo. Escolher os eventos certos reduz tráfego e simplifica o handler.
| Grupo | Eventos | Para que serve no seu produto |
|---|---|---|
| Mensagens | messages.received, messages.sent |
Inbox, chatbot, agente de IA, histórico |
| Status | message.delivered, message.read, message.deleted |
Ticks de entrega e leitura, auditoria |
| Conexão | connection.qrcode, connection.paircode, connection.status, session.created |
Onboarding do cliente e alerta de desconexão |
| Chats e contatos | chats.upsert, chats.update, contacts.upsert, contacts.update, presence |
Lista de conversas, “digitando” |
| Grupos | groups_participants.join, .leave, .promote, .demote e pedidos de entrada |
Comunidades e gestão de grupos |
| Etiquetas | labels.edit, labels.association.chat, labels.association.message |
Sincronia com o funil do CRM |
| Chamadas | call.offer, call.ringing, call.connected, call.ended, call.audio e outros |
Registro e atendimento de ligações |
Três comportamentos evitam bugs comuns. Mensagens enviadas pela sua integração chegam como messages.sent, e um messages.received com fromMe: true indica envio feito pelo próprio número em outro aparelho. Edições chegam em messages.received com type: "edited_message", porque message.update não é disparado. E o logout nunca vem como evento próprio: ele chega em connection.status com data.status: "logged_out", então o seu código deve olhar logged_out e disconnected para pedir reconexão ao cliente.
Para quem atende por voz, os eventos call.* estão detalhados no artigo sobre a API de ligações. Um aviso vale desde já: o call.audio em chunks ao vivo pode gerar cerca de um evento por segundo por chamada, então só habilite se for consumir o áudio.
Configurar o webhook por sessão
Cada sessão tem a própria configuração, o que permite que um cliente do seu SaaS receba um conjunto de eventos diferente de outro.
A URL pode ser definida já na criação (webhookUrl em POST /api/v1/sessions) ou trocada depois com POST /api/v1/sessions/{sessionId}/webhook. Para escolher quais eventos ligar e para onde cada um vai, use POST /api/v1/sessions/{sessionId}/webhook-config. Há dois modos: single, em que todos os eventos habilitados vão para a mesma URL, e per_event, em que cada evento tem a sua webhookUrl.
curl -X POST https://api.d-api.cloud/api/v1/sessions/minha-sessao/webhook-config \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"type": "per_event",
"events": {
"messages.received": { "enabled": true, "webhookUrl": "https://seu-saas.com/hooks/inbox/TOKEN" },
"connection.status": { "enabled": true, "webhookUrl": "https://seu-saas.com/hooks/ops/TOKEN" },
"call.audio": { "enabled": false }
}
}'
Eventos desabilitados não são enviados. Separar o tráfego de inbox do tráfego operacional, como no exemplo, ajuda a escalar cada endpoint de forma independente.
Como a D-API entrega: retentativa, timeout e deduplicação
O resultado para o seu SaaS é não perder evento quando o seu endpoint oscila. A contrapartida é que o seu handler precisa estar preparado para receber o mesmo evento mais de uma vez. A política documentada é esta:
- Retentativas: até 7 tentativas com backoff exponencial, com intervalos de aproximadamente 5s, 10s, 20s, 40s, 80s e 160s.
- Timeout: cada tentativa espera 30 segundos. Um endpoint lento conta como falha e entra em retentativa.
- Falhas permanentes: respostas HTTP 404 ou 410 encerram as tentativas para aquela URL.
- Circuit breaker: existe um por URL. Endpoints que falham repetidamente são interrompidos temporariamente para evitar sobrecarga.
- Deduplicação: eventos passam por deduplicação via Redis com TTL de 5 minutos, o que reduz entregas duplicadas em intervalo curto.
Daí saem quatro regras para o handler. Responda 2xx o mais rápido possível e mova o processamento para uma fila ou worker. Não devolva 404 ou 410 por erro de roteamento interno, porque a D-API vai entender que a URL deixou de existir. Faça o processamento idempotente, usando o data.id da mensagem (ou event mais traceId) como chave, já que a deduplicação da D-API cobre só 5 minutos e a sua retentativa pode passar disso. E registre o traceId em log estruturado.
app.post("/hooks/inbox/:token", async (req, res) => {
if (req.params.token !== process.env.DAPI_WEBHOOK_TOKEN) return res.sendStatus(401);
const { event, sessionId, data, traceId } = req.body;
logger.info({ event, sessionId, traceId }, "webhook recebido");
await queue.publish("dapi-events", { event, sessionId, data, traceId });
res.sendStatus(200);
});
O worker que consome dapi-events é onde mora a regra de negócio: gravar a mensagem, atualizar o ticket, chamar o agente de IA. Ele pode demorar o quanto precisar sem afetar a entrega.
Fila RabbitMQ por sessão
Se o seu SaaS já opera um broker, receber os eventos direto numa fila RabbitMQ elimina o endpoint HTTP intermediário e entrega controle de consumo, prefetch e reprocessamento ao seu time.
A configuração também é por sessão, em POST /api/v1/sessions/{sessionId}/rabbitmq-config. Com enabled: true, a validação exige host, port, username e password. Na prática, informe também exchange e o mapa events: a publicação acontece no exchange que você indicar e só para os eventos marcados com enabled: true nesse mapa, cujas chaves são os nomes dos eventos. Sem events, nada é publicado. O vhost é opcional:
curl -X POST https://api.d-api.cloud/api/v1/sessions/minha-sessao/rabbitmq-config \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"host": "rabbit.seu-saas.com",
"port": 5672,
"username": "dapi",
"password": "SENHA_DO_BROKER",
"vhost": "/whatsapp",
"exchange": "dapi.events",
"events": {
"messages.received": { "enabled": true },
"history.message.upsert": { "enabled": true }
}
}'
Para desligar, envie { "enabled": false }.
O que chega no seu broker
Ao conectar, a D-API declara no seu broker o exchange informado, do tipo direct e durável. A declaração é idempotente, então você pode criá-lo antes com as mesmas propriedades. Cada evento é publicado nesse exchange com routing key vazia, como mensagem persistente, com content-type: application/json e o horário de publicação na propriedade timestamp, sem headers customizados. O campo routingKey é aceito na configuração, mas hoje não altera a publicação.
O corpo é o mesmo envelope do webhook (event, sessionId, data, timestamp e traceId), então o parser serve para os dois caminhos. A diferença está em data, que chega como foi gerado, sem os campos de conveniência que o webhook acrescenta, como os objetos location e contact já interpretados. Para consumir, crie a sua fila e faça o bind no exchange com binding key vazia:
import amqp from "amqplib";
const conn = await amqp.connect(process.env.RABBITMQ_URL!);
const ch = await conn.createChannel();
await ch.assertExchange("dapi.events", "direct", { durable: true });
await ch.assertQueue("whatsapp-eventos", { durable: true });
await ch.bindQueue("whatsapp-eventos", "dapi.events", "");
await ch.prefetch(20);
await ch.consume("whatsapp-eventos", async (msg) => {
if (!msg) return;
const { event, sessionId, data, traceId } = JSON.parse(msg.content.toString());
try {
await handleEvent({ event, sessionId, data, traceId });
ch.ack(msg);
} catch (err) {
logger.error({ err, event, sessionId, traceId }, "falha ao processar evento");
ch.nack(msg, false, false);
}
});
Várias sessões podem apontar para o mesmo exchange, e o sessionId do corpo leva cada evento ao tenant certo. Com nack sem requeue, configure uma dead-letter queue na sua fila para guardar o que falhou. Vale saber também que, se o seu broker ficar inacessível, a D-API reconecta com backoff, mas o evento daquela publicação não é reenviado. Para reconciliar uma janela de indisponibilidade, use GET /api/v1/chats/{chatId}/messages.
Há uma diferença de conteúdo que pode decidir a escolha. Durante a sincronização de histórico, history.message.upsert e history.message.received são suprimidos no webhook para evitar uma enxurrada de chamadas, e ficam disponíveis apenas via RabbitMQ. Já history.messages.sent chega no webhook convertido em messages.received com fromMe: true (somente os recentes, com menos de 5 minutos), enquanto no RabbitMQ mantém o nome original. Se o seu produto importa o histórico do cliente ao conectar, a fila é o caminho completo. Os detalhes de cada evento estão na documentação da D-API.
Webhook ou fila, como decidir
Use webhook quando você quer começar rápido, o volume é moderado e o time prefere não operar broker. A política de retentativa da D-API já cobre oscilações do seu endpoint.
Use RabbitMQ quando você já tem a infraestrutura, quer controlar consumo e reprocessamento com ferramentas do próprio broker ou precisa do histórico completo das conversas. Nada impede combinar os dois: webhook para eventos de conexão que o time de operação acompanha e fila para o fluxo de mensagens.
O formato dos eventos também independe do tipo de conexão. Uma conexão da API Oficial configurada com webhookMode: "normalized" entrega o mesmo payload canônico da não-oficial, então o seu handler serve para as duas. O custo de mensagens desses clientes segue a tabela de preços da Meta, cobrado na conta Meta de cada um.
Por onde começar
Suba um endpoint que valida o token, registra o traceId, publica numa fila interna e responde 200. Crie uma sessão com webhookUrl apontando para ele, conecte um número de teste e envie uma mensagem para esse número. O primeiro messages.received vai mostrar o envelope na prática.
Com isso funcionando, ligue connection.status para alertar clientes desconectados, garanta idempotência pelo data.id e decida, conforme o seu volume e a necessidade de histórico, se vale mover o fluxo de mensagens para RabbitMQ.
Veja também: Integração, API de WhatsApp.
Perguntas frequentes
O webhook da D-API tem assinatura HMAC?
Não. A recomendação da documentação é usar uma URL secreta, com token no path, e validar o User-Agent (Deliverify-Webhook/1.0) e o sessionId esperado.
O que acontece se o meu endpoint ficar fora do ar?
A entrega é repetida até 7 vezes com backoff exponencial. Respostas 404 ou 410 encerram as tentativas para aquela URL, e um circuit breaker por URL pausa temporariamente endpoints que falham repetidamente.
Posso receber eventos diferentes em URLs diferentes?
Sim. No modo per_event cada evento tem a própria webhookUrl. No modo single, todos os eventos habilitados vão para a mesma URL.
Mensagens enviadas pela API geram messages.received?
Não. Envios feitos pela API geram messages.sent. O messages.received com fromMe true aparece para mensagens enviadas pelo próprio número em outro aparelho.
Quando vale usar RabbitMQ no lugar do webhook?
Quando você já opera um broker ou precisa dos eventos de histórico history.message.upsert e history.message.received, que são suprimidos no webhook e só chegam via RabbitMQ.