WACrew

Blog

Webhooks de WhatsApp explicados para desenvolvedores

Como funcionam os webhooks da API oficial do WhatsApp. Verificação com hub.challenge, assinatura X-Hub-Signature-256, formato das mensagens e status, reenvio e boas práticas.

Por Rodrigo Sumioshi 5 min de leitura
Neste artigo
  1. O que o seu endpoint precisa ter
  2. Requisição 1: verificação (GET)
  3. Requisição 2: eventos (POST)
  4. Validando a assinatura
  5. Um endpoint completo em Node
  6. Reenvio e duplicatas
  7. Uma mudança recente: identificador por usuário
  8. E nas APIs não oficiais?
  9. Checklist do webhook

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.mode vem sempre como subscribe;
  • 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:

  1. 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.
  2. 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.
  3. Duplicatas. Por causa do reenvio, o mesmo evento pode chegar mais de uma vez. Guarde o id de cada mensagem (o wamid) 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.challenge só com o token certo;
  • Assinatura conferida sobre o corpo bruto;
  • 200 rápido e processamento em fila;
  • Deduplicação pelo ID da mensagem;
  • Tratamento de messages e de statuses;
  • 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.