Webhook WhatsApp Business API: Como Configurar

Configurar um webhook na WhatsApp Business API é o passo decisivo para transformar a integração em um canal verdadeiramente bidirecional. Sem o webhook devidamente registrado, sua aplicação consegue enviar mensagens, mas perde toda a camada de eventos recebidos: respostas de clientes, atualizações de status de entrega, leitura de mensagens, mudanças em templates e notificações da própria plataforma. Para operações de atendimento, automação e conformidade regulatória, esse fluxo de retorno é o que dá vida ao canal.

Neste guia técnico, a Comunicação em Massa apresenta o passo a passo completo para configurar o webhook da WhatsApp Business API, desde a preparação da URL receptora até a validação de assinatura HMAC, tratamento dos payloads e estratégias de debug. O conteúdo é direcionado a desenvolvedores, arquitetos de integração e gestores técnicos responsáveis por colocar a API oficial em produção com segurança e estabilidade.

Pré-requisitos para configurar o webhook

Antes de iniciar a configuração propriamente dita, certifique-se de que os seguintes recursos estão disponíveis e operacionais. Pular qualquer um desses itens resulta em falhas de verificação ou em eventos perdidos no momento da subida.

• URL pública HTTPS válida: a Meta exige um endpoint acessível pela internet, com certificado TLS confiável (não autoassinado). O domínio precisa resolver corretamente em DNS público e responder na porta 443. Endpoints atrás de VPN, com IP dinâmico sem DNS dinâmico ou em desenvolvimento via localhost só funcionam mediante túneis como ngrok, Cloudflare Tunnel ou similares.
• Conta no Meta Business Manager: é obrigatório possuir uma conta Business verificada associada ao número de telefone que será usado na API. A verificação de negócio (Business Verification) é pré-requisito para sair do modo sandbox e enviar mensagens em escala.
• App no painel de desenvolvedores Meta: crie um aplicativo no painel developers.facebook.com, adicione o produto WhatsApp e gere o token de acesso permanente do sistema (System User Token). Mantenha à mão o Phone Number ID e o WhatsApp Business Account ID (WABA ID).
• Servidor capaz de responder em até 5 segundos: o tempo limite padrão para confirmação do POST é curto, e atrasos disparam retry agressivo do lado da Meta.

Passo a passo: como configurar o webhook

1. Crie a URL receptora com token de validação.
   Implemente um endpoint HTTP no seu backend, por exemplo POST /webhook/whatsapp e GET /webhook/whatsapp. Defina uma constante secreta VERIFY_TOKEN que será compartilhada apenas entre seu servidor e o painel da Meta. Esse token serve para confirmar que a URL realmente pertence a você no momento da inscrição.
2. Registre a URL no painel da Meta.
   No painel do app, navegue até WhatsApp, em seguida Configuration. Em Webhook, clique em Edit, informe a URL HTTPS completa do seu endpoint e cole o mesmo VERIFY_TOKEN definido no servidor. Selecione a versão da Graph API que sua aplicação suporta (recomendado v18.0 ou superior, conforme disponibilidade).
3. Trate o challenge GET de verificação.
   Ao salvar, a Meta dispara um GET contendo três parâmetros de query: hub.mode=subscribe, hub.verify_token e hub.challenge. Seu servidor deve verificar se o token recebido bate com o esperado e responder com o valor exato de hub.challenge em texto plano e status 200. Qualquer divergência aborta a assinatura.

   // Node.js / Express
   app.get('/webhook/whatsapp', (req, res) => {
     const mode = req.query['hub.mode'];
     const token = req.query['hub.verify_token'];
     const challenge = req.query['hub.challenge'];
     if (mode === 'subscribe' && token === process.env.VERIFY_TOKEN) {
       return res.status(200).send(challenge);
     }
     return res.sendStatus(403);
   });

4. Inscreva-se nos campos do WABA.
   Após a verificação, no mesmo painel selecione os campos (fields) que deseja receber: messages (mensagens recebidas e status de entrega), message_template_status_update, account_update, phone_number_quality_update, entre outros. Cada campo é independente e pode ser ativado ou desativado conforme a necessidade.
5. Processe os POST events.
   A partir desse momento, todo evento será entregue como POST em formato JSON. A estrutura traz um array entry, cada item com changes que descrevem o tipo de evento (field) e o conteúdo (value). Sempre responda com status 200 imediatamente, mesmo que o processamento real seja assíncrono, para evitar reentregas desnecessárias.
6. Trate os payloads de mensagem, status e template.
   Os principais subtipos a tratar são: mensagens recebidas (messages com texto, mídia, localização, contatos, interativos, button reply e list reply); status (statuses com sent, delivered, read, failed); e templates (message_template_status_update com APPROVED, REJECTED, FLAGGED). Faça parse seguro e roteie cada subtipo para o handler correspondente na sua aplicação.
7. Valide a assinatura X-Hub-Signature-256.
   Toda requisição POST traz o cabeçalho X-Hub-Signature-256 com um HMAC SHA-256 do corpo bruto, assinado com o App Secret. Calcule a assinatura no seu lado e compare em tempo constante. Requisições sem assinatura válida devem ser descartadas, pois indicam tentativa de spoofing.

   const crypto = require('crypto');
   function isValidSignature(rawBody, headerSig, appSecret) {
     const expected = 'sha256=' + crypto
       .createHmac('sha256', appSecret)
       .update(rawBody)
       .digest('hex');
     return crypto.timingSafeEqual(
       Buffer.from(expected),
       Buffer.from(headerSig || '')
     );
   }

8. Implemente fila e idempotência.
   Após validar a assinatura, encaminhe o payload para uma fila (Redis, RabbitMQ, SQS, Kafka). Use o id de cada mensagem como chave de idempotência: a Meta pode reentregar o mesmo evento em caso de timeout, e o consumidor não deve processá-lo duas vezes.
9. Maneje erros e retry.
   Em caso de erro 5xx no seu endpoint, a Meta tenta reentregar com backoff exponencial por aproximadamente 7 dias. Monitore taxas de erro, latência p95 e volume de retry. Implemente DLQ (Dead Letter Queue) para eventos que falharem repetidamente após processamento interno, e dispare alertas operacionais quando a taxa exceder um limiar acordado.

Eventos suportados pelo webhook

O webhook da WhatsApp Business API entrega uma gama ampla de eventos que cobrem o ciclo completo de comunicação. Os principais são:

• messages: mensagens recebidas dos usuários, incluindo texto, imagem, áudio, documento, vídeo, sticker, localização, contato e interativos como botões e listas.
• statuses: atualizações de entrega das mensagens enviadas (sent, delivered, read, failed), incluindo categorização de conversa para fins de billing.
• message_template_status_update: mudanças no status de aprovação de templates pré-cadastrados.
• phone_number_quality_update: sinais de qualidade do número (green, yellow, red), essenciais para evitar suspensão por baixa reputação.
• account_alerts e account_update: alterações no status da conta e alertas de compliance.

Detalhes sobre como esses eventos se conectam ao fluxo de atendimento e CRM podem ser conferidos em nosso material de integrações entre WhatsApp Business e CRM, que aborda os principais pontos de captura e enriquecimento de dados.

Segurança e conformidade

A camada de webhook é o ponto mais sensível da integração, pois recebe dados pessoais em tempo real. Adote as seguintes práticas mínimas:

• Force HTTPS com TLS 1.2 ou superior e desabilite ciphers fracos.
• Valide sempre X-Hub-Signature-256 com comparação em tempo constante.
• Restrinja, quando possível, o acesso ao endpoint por IPs da Meta via firewall ou WAF.
• Armazene o App Secret e o VERIFY_TOKEN em um cofre de segredos, nunca em código-fonte versionado.
• Aplique princípios de minimização de dados: armazene apenas o necessário, pseudonimize identificadores e defina retenção curta para mídias temporárias.
• Mantenha registros de consentimento e base legal conforme exigido pela LGPD. Para orientações regulatórias, consulte a Autoridade Nacional de Proteção de Dados.

Para um panorama completo de como conectar essa camada a sistemas internos, recomendamos a leitura do guia de integração WhatsApp e CRM passo a passo.

Debug e troubleshooting

Mesmo com a configuração correta, problemas surgem em produção. As situações mais frequentes e suas abordagens:

• Verificação inicial falhando: confirme que o servidor responde 200 com o valor exato do hub.challenge, sem aspas, sem JSON e sem caracteres extras. Cabeçalhos Content-Type: text/plain ajudam a evitar reescrita por proxies.
• Eventos não chegam: revise os fields inscritos no painel e cheque se a versão da Graph API é compatível com a estrutura esperada. Use o botão Test do painel para disparar payloads sintéticos.
• Assinatura sempre inválida: verifique se o corpo está sendo lido como buffer cru, antes de qualquer parse JSON. Frameworks que aplicam middleware de body parser podem alterar bytes e quebrar o HMAC.
• Latência alta: mova o processamento para fila assíncrona e responda 200 em milissegundos. Operações pesadas, gravação em banco, chamadas a IA e envio de respostas devem acontecer fora do ciclo de request original.
• Loop de retry: identifique no log o id recorrente e investigue se o handler está lançando exceção. Adicione circuit breaker para evitar consumo excessivo de recursos.

Para complementar, o ideal é adotar observabilidade end-to-end: tracing distribuído, métricas de SLA e alertas automatizados.

FAQ: dúvidas frequentes sobre webhook WhatsApp Business API

1. Posso usar mais de um webhook por número?

Não. Cada WABA suporta apenas uma URL de webhook ativa por aplicativo. Caso precise distribuir eventos para múltiplos consumidores, implemente um fan-out interno (pub/sub, fila, message broker) após receber e validar o payload.

2. O que acontece se meu servidor ficar fora do ar?

A Meta reentrega os eventos por aproximadamente 7 dias com backoff exponencial. Após esse período, eventos não confirmados são descartados. Por isso, alta disponibilidade e fila persistente são essenciais.

3. Preciso verificar a assinatura mesmo em ambiente de homologação?

Sim. Pular a validação cria hábitos inseguros e expõe seu sistema a injeção de payloads falsos. Use o mesmo App Secret entre dev e prod ou crie um app de teste com secret próprio, mas nunca desligue a checagem.

4. Como tratar mensagens recebidas fora do horário comercial?

O webhook entrega o evento normalmente. Cabe à sua aplicação registrar a mensagem, responder com template fora do horário (se aplicável) e enfileirar para atendimento humano no próximo turno, respeitando a janela de 24 horas para mensagens livres.

5. Existe limite de eventos por segundo?

A Meta não publica um teto rígido, mas dimensione seu endpoint para suportar picos de pelo menos centenas de requisições por segundo em contas de alto volume. Testes de carga antes do go-live são altamente recomendados.

Para conhecer outros materiais técnicos e operacionais, explore nossos recursos completos ou avalie nossos planos disponíveis.

Conteúdo relacionado

• Integracoes whatsapp business
• Whatsapp rd station integracao
• Whatsapp hubspot integracao
• Whatsapp zapier automacoes
• Api whatsapp ecommerce integracoes