Como configurar o webhook da API do WhatsApp?

O que é um Webhook? (O Carteiro da Internet)

Para simplificar o conceito arquitetural de dev: Se a REST API é a sua empresa bater na porta do Facebook para enviar um dado com (GET/POST), o Webhook é o Facebook bater na porta do seu servidor para informar algo instantaneamente sempre que acontece uma ação humana, evitando que sua aplicação precise consultar os servidores de Mark Zuckerberg de minuto em minuto eternamente (o temido polling infinito).

Como Configurar e Tratar Eventos "WABA" (Status Changes)

Quando sua equipe conecta o Dashboard da Hablas ao App Oficial da Meta, nossa malha tecnológica registra um campo Callback URL de recepção. Nós transformamos a imensa bagunça JSON crua da Meta num modelo limpo, disparando diretamente para a sua API final (seja em PHP, Laravel, Node.JS ou num n8n).

A Estrutura de Tratamento Obrigatória do Dev Backend:

1. Validação de Challenge Hub: Inicialmente, a Meta/Hablas efetuará um GET enviando um número aleatório (hub.challenge). Você deve codar sua API para ecossar responder esse número na tela num Payload simples de 200 OK para confirmar a propriedade (Verify Token).
2. Paralelismo de Status: Todo pacote (POST) recebido deve ser tratado via Async Job (Fila SQS ou RabbitMQ). Jamais trave a resposta tentando resolver a regra de negócios. Devolva um {status: "received"} na linha 1 da sua função, e envie a leitura da mensagem para Background Workers (filas virtuais). Um webhook lento (acima de 3 segundos de resposta) acarretará falhas de SLA e bloqueio da url.
3. Eventos de Status Ticks: O Payload disparará três vezes por simples envio. Escute as palavras chaves do objeto `status`: Entregue ("delivered"), Recebido pelo celular ("sent"), e Lido pelos olhinhos humanos ("read").

Como configurar o webhook da API do WhatsApp?

No Meta for Developers, acesse o App > WhatsApp > Configuração > Webhook. Insira a URL do seu servidor (HTTPS obrigatório) e um Verify Token. A Meta fará um GET com hub.challenge e você deve retornar o valor. Depois, ative os campos: messages, message_deliveries e message_reads.

O que fazer quando o webhook não está recebendo mensagens?

Verifique: (1) se o servidor responde em menos de 3 segundos com HTTP 200; (2) se o SSL/HTTPS está válido; (3) se os campos de assinatura estão ativados no painel da Meta; (4) se o webhook foi verificado com sucesso. Use ngrok para testar localmente antes de publicar.

Como tratar os eventos de status via webhook?

O payload contém o campo statuses com os valores: sent (enviado ao servidor da Meta), delivered (entregue ao celular do destinatário) ou read (lido pelo usuário). Responda HTTP 200 imediatamente e processe a lógica em background com filas assíncronas.

Qual a diferença entre webhook e polling na API do WhatsApp?

Polling é quando sua aplicação consulta a API periodicamente para verificar novos eventos — ineficiente e com delay. Webhook é o oposto: a Meta notifica seu servidor instantaneamente. A API Oficial só suporta webhook, tornando o sistema mais rápido e eficiente.

Perguntas Frequentes