Webhooks do WhatsApp: como receber mensagens no seu sistema

Enviar pela API oficial é uma requisição HTTP e resolve em dez minutos. Receber é onde o projeto realmente começa — e é a parte que surpreende quem imaginava algo mais simples.

Não existe “consultar mensagens novas”. A Meta empurra os eventos para você, e isso significa um servidor público, sempre no ar.

Como funciona

Configuração

1. 1

   Tenha uma URL pública com HTTPS

   Precisa ser acessível pela internet, com certificado válido. Em desenvolvimento, um túnel resolve; em produção, é um servidor de verdade.

2. 2

   Implemente a verificação (GET)

   Ao cadastrar a URL, a Meta faz um GET com hub.mode, hub.verify_token e hub.challenge. Confira se o token bate com o seu e devolva o hub.challenge como texto puro. É aqui que quase todo mundo trava na primeira vez.

3. 3

   Implemente o recebimento (POST)

   Os eventos chegam como POST em JSON. Responda 200 imediatamente, antes de processar — a Meta reenvia o que demora a ser confirmado.

4. 4

   Assine os campos que interessam

   No painel, escolha os campos do webhook. messages cobre mensagens recebidas e status de entrega, e é o essencial.

// verificação — a Meta chama uma vez, ao cadastrar a URL
app.get("/webhook", (req, res) => {
  const modo = req.query["hub.mode"];
  const token = req.query["hub.verify_token"];

  if (modo === "subscribe" && token === process.env.VERIFY_TOKEN) {
    return res.status(200).send(req.query["hub.challenge"]);
  }
  res.sendStatus(403);
});

// recebimento — responda 200 antes de processar
app.post("/webhook", (req, res) => {
  res.sendStatus(200);
  enfileirar(req.body);
});

O que a Meta manda

O corpo é aninhado e o dado útil está fundo. Vale conhecer o formato antes de escrever o parser:

{
  "entry": [{
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "contacts": [{ "wa_id": "558599999999", "profile": { "name": "Marina" } }],
        "messages": [{
          "from": "558599999999",
          "id": "wamid.HBgNNTU...",
          "timestamp": "1789567890",
          "type": "text",
          "text": { "body": "Quero um orçamento" }
        }]
      },
      "field": "messages"
    }]
  }]
}

Os tipos de evento

Os quatro problemas que todo mundo encontra

1. 1Mensagem repetida. A Meta reenvia quando não recebe 200 rápido. A correção não é acelerar o processamento — é guardar o `id` da mensagem e ignorar o que já foi visto. Sem isso, o cliente recebe a mesma resposta três vezes.
2. 2Ordem trocada. Os eventos não chegam necessariamente na ordem em que aconteceram. Use o timestamp, não a ordem de chegada.
3. 3Endpoint fora do ar. A Meta tenta de novo por um tempo e depois desiste — e pode desativar a assinatura se o erro persistir. Monitore o webhook como serviço crítico, porque é isso que ele é.
4. 4Assinatura não validada. Sem validar, qualquer um que descubra sua URL injeta eventos falsos no seu sistema.

Validar a assinatura

Todo POST vem com o cabeçalho X-Hub-Signature-256, que é um HMAC SHA-256 do corpo cru usando o segredo do seu app.

import crypto from "node:crypto";

function assinaturaValida(corpoCru, cabecalho) {
  const esperado =
    "sha256=" +
    crypto.createHmac("sha256", process.env.APP_SECRET)
          .update(corpoCru)
          .digest("hex");

  // timingSafeEqual, e não ===: comparação comum vaza o tempo de acerto
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(cabecalho));
}

Guardar o corpo cru antes do parser de JSON é o detalhe que faz a validação funcionar — e a causa da maioria dos “minha assinatura nunca confere”.

Webhook e a janela de 24 horas

Todo evento em messages reinicia a janela daquele cliente. Vale registrar o horário: é o que permite saber se ainda dá para responder com texto livre ou se já é caso de template.

• Guarde timestamp da última mensagem recebida por contato.
• Antes de enviar, compare com agora: menos de 24h, texto livre; mais, template.
• Toque em botão também conta e reabre a janela.
• O mecanismo completo está em janela de 24 horas.

Quem constrói produto para terceiros e precisa conectar a conta de cada cliente deve olhar o Embedded Signup, que registra a assinatura de webhook automaticamente ao fim do fluxo.

Antes de construir tudo isso

Webhook exige servidor no ar, fila, deduplicação, validação de assinatura e monitoramento. É trabalho de infraestrutura contínuo, não de uma semana.

Existe um meio-termo: ferramentas de automação visual recebem o webhook por você e entregam a URL pronta, o que resolve a parte chata sem escrever servidor — o caminho está em integrar o WhatsApp com n8n, Make e Zapier.

Vale conferir se você precisa mesmo. Para atendimento de dezenas de conversas por dia, o WhatsApp Business gratuito entrega o mesmo resultado sem nada disso. A API compensa quando a mensagem precisa sair de um sistema ou quando o volume de atendimento passou do que quatro pessoas dão conta.

Perguntas frequentes

Resumo

• Webhook é a única forma de receber mensagens: exige URL pública com HTTPS.
• Responda ao GET de verificação devolvendo o hub.challenge como texto puro.
• Responda 200 antes de processar e deduplique pelo id da mensagem.
• Valide a assinatura sobre o corpo cru, com comparação de tempo constante.
• No Brasil, o wa_id costuma vir sem o nono dígito — use-o como identificador.