Na API oficial do WhatsApp, você não pergunta se chegou mensagem. É o WhatsApp que avisa o seu servidor, fazendo uma requisição HTTP para uma URL sua cada vez que algo acontece. Essa URL é o webhook. Mensagem nova, mensagem entregue, mensagem lida, tudo chega por ali.
Este guia explica as duas requisições que o seu endpoint recebe, como validar que vieram mesmo da Meta e como ler o conteúdo, com base na documentação de webhooks da Meta e na referência de webhooks da Cloud API.
O que o seu endpoint precisa ter
- Uma URL pública com HTTPS e certificado válido. A documentação é clara que certificados autoassinados não são aceitos.
- Uma rota que responde a GET, para a verificação.
- A mesma rota respondendo a POST, para os eventos.
- Um token de verificação que você inventa e cadastra no painel do app.
- O App Secret do seu app, para conferir a assinatura dos eventos.
Requisição 1: verificação (GET)
Quando você cadastra a URL no painel do app, a Meta faz um GET com três parâmetros.
GET https://seu-dominio.com/webhooks?hub.mode=subscribe&hub.challenge=1158201444&hub.verify_token=meu-token
hub.modevem sempre comosubscribe;hub.challengeé um número que você precisa devolver;hub.verify_tokené o token que você cadastrou.
O seu código confere se o token bate e, se bater, responde com o valor de hub.challenge. Se não bater, responde com erro.
Requisição 2: eventos (POST)
A partir daí, cada evento chega como um POST com corpo JSON e o cabeçalho X-Hub-Signature-256. Uma mensagem de texto recebida tem este formato (resumido do exemplo da documentação):
{
"object": "whatsapp_business_account",
"entry": [{
"id": "102290129340398",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
"contacts": [{ "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" }],
"messages": [{
"from": "16505551234",
"id": "wamid.HBgLMTY1...",
"timestamp": "1749416383",
"type": "text",
"text": { "body": "Does it come in another color?" }
}]
}
}]
}]
}
Repare na estrutura em camadas: entry é uma lista, changes é outra lista, e dentro de value vêm messages (mensagens recebidas) ou statuses (atualizações das mensagens que você enviou, como sent, delivered e read). O phone_number_id diz para qual número da sua empresa a mensagem foi, o que importa quando você tem mais de um.
Mensagens de mídia trazem type igual a image, audio, document e assim por diante, com um ID que você usa para baixar o arquivo pela API.
Validando a assinatura
Qualquer pessoa que descubra a sua URL pode mandar um POST para ela. A assinatura resolve isso. A Meta calcula um HMAC SHA-256 do corpo da requisição usando o App Secret do seu app e manda o resultado no cabeçalho, com o prefixo sha256=. Você calcula do seu lado e compara.
O detalhe que mais derruba gente: a conta precisa ser feita sobre o corpo bruto, exatamente os bytes que chegaram. Se o framework já transformou o corpo em objeto e você fizer JSON.stringify de novo, a assinatura não bate.
Um endpoint completo em Node
import express from "express";
import crypto from "node:crypto";
const app = express();
const VERIFY_TOKEN = process.env.WHATSAPP_VERIFY_TOKEN!;
const APP_SECRET = process.env.META_APP_SECRET!;
// Verificação
app.get("/webhooks", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).send(req.query["hub.challenge"]);
});
// Eventos: corpo bruto para conferir a assinatura
app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
const assinatura = req.get("X-Hub-Signature-256")?.replace("sha256=", "") ?? "";
const esperada = crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex");
const valida =
assinatura.length === esperada.length &&
crypto.timingSafeEqual(Buffer.from(assinatura), Buffer.from(esperada));
if (!valida) return res.sendStatus(401);
res.sendStatus(200); // responda rápido; processe depois
const evento = JSON.parse(req.body.toString("utf8"));
enfileirar(evento);
});
app.listen(3000);
Duas escolhas desse código são de propósito. A comparação usa timingSafeEqual, que não vaza informação pelo tempo de resposta. E o 200 sai antes do processamento, porque o trabalho pesado (chamar uma IA, gravar no banco) vai para uma fila.
Reenvio e duplicatas
A documentação da Meta descreve três comportamentos que o seu código precisa aguentar:
- Lotes. Os eventos podem vir agrupados, com até mil atualizações, mas o agrupamento não é garantido. Trate cada item da lista de forma independente.
- Reenvio. Se o seu servidor não confirmar com
200, a Meta tenta de novo na hora e depois algumas vezes, com intervalos cada vez maiores, por até 36 horas. - Duplicatas. Por causa do reenvio, o mesmo evento pode chegar mais de uma vez. Guarde o
idde cada mensagem (owamid) e ignore o que já processou.
Na prática, isso significa responder rápido, gravar o evento e processar em segundo plano, com uma checagem de "já vi esse ID?".
Uma mudança recente: identificador por usuário
A referência da Cloud API documenta que, quando o usuário do WhatsApp tem um nome de usuário, os webhooks podem identificá-lo por um ID com escopo da empresa, e o número de telefone pode não vir. Se o seu sistema usa o telefone como chave do cliente, vale ler essa parte da documentação e prever os dois casos.
E nas APIs não oficiais?
APIs que rodam sobre o WhatsApp Web, como Evolution API e WAHA, também entregam eventos por webhook, mas cada uma com o próprio formato e o próprio jeito de autenticar. A lógica é a mesma (responder rápido, enfileirar, evitar duplicata), só os campos mudam. A comparação entre elas está em WAHA ou Evolution API, e a visão geral em melhores APIs de WhatsApp.
Já quem usa o WhatsApp Web direto com uma biblioteca como o Baileys não recebe webhook nenhum. Os eventos chegam pela conexão aberta, dentro do próprio processo.
Checklist do webhook
- HTTPS com certificado válido;
- GET devolvendo
hub.challengesó com o token certo; - Assinatura conferida sobre o corpo bruto;
200rápido e processamento em fila;- Deduplicação pelo ID da mensagem;
- Tratamento de
messagese destatuses; - Log de cada evento recebido, para depurar depois.
Com isso, o seu endpoint aguenta tráfego real sem perder nem repetir mensagem. Para levar o projeto adiante com IA, veja como criar um agente de IA para WhatsApp com Claude.



