Configurar webhooks do WhatsApp Business em 2026 exige uma URL de retorno de chamada HTTPS pública, um token de verificação para o handshake com a Meta, lógica para processar eventos JSON recebidos (mensagens, status, modelos, business_capability) e tratamento de recuperação. Para empresas com uma equipe de engenharia, este é o caminho para máxima flexibilidade; para todos os outros, uma plataforma como o Aurora Inbox absorve toda a complexidade e deixa os webhooks específicos da aplicação para serem tratados quando necessário.
O que é um webhook do WhatsApp Business?
Um webhook é um endpoint HTTPS público para o qual o Meta envia uma requisição POST sempre que ocorre um evento na sua conta do WhatsApp Business: mensagem recebida, alteração de status (entregue, lida), aprovação de modelo, alteração na qualidade do número.
Sem webhooks, não há como saber o que está acontecendo na sua API. Eles são a forma "push" que o Meta usa para te notificar.
Tipos de eventos webhook
A Meta envia cinco categorias de eventos:
| Evento | Quando ele dispara | Caso de uso |
|---|---|---|
mensagens |
O cliente envia mensagem | Processe a mensagem e responda. |
status |
Alteração do status de uma mensagem de saída | Rastreamento de entrega, leia |
atualização_de_status_do_modelo |
Modelo aprovado/rejeitado/pausado | Atualize a interface do usuário do seu modelo. |
atualização_de_capacidade_de_negócios |
Alterações de nível, qualidade ou capacidades. | Alertas precoces de problemas |
atualização_de_qualidade_do_número_de_telefone |
Alterações na qualidade do verde/amarelo/vermelho | Reaja antes do banimento. |
Configure o webhook diretamente com a API do Cloud.
Passo 1: Tenha uma URL de retorno de chamada HTTPS pública
Seu servidor deve ser:
- HTTPS Com certificado válido (Meta rejeita HTTP).
- Público (não é localhost, nem IP interno).
- Ponto final específico para webhook (por exemplo,
https://tu-dominio.com/webhooks/whatsapp).
Para o desenvolvimento local, túneis tipo ngrok ou similares funcionam.
Etapa 2: Implementar o handshake de verificação
A Meta envia uma solicitação GET inicial para verificar o URL de retorno de chamada:
GET /webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=SEU_TOKEN&hub.challenge=12345
Seu servidor deve:
- Confirme que
hub.verify_tokenEle corresponde ao token que você registrou. - Retornar
desafio do hubcomo uma resposta categórica.
Exemplo em Node.js Express:
app.get('/webhooks/whatsapp', (req, res) => { if (req.query['hub.verify_token'] === process.env.WHATSAPP_VERIFY_TOKEN) { res.send(req.query['hub.challenge']); } else { res.status(403).send('Proibido'); } });
Etapa 3: Processar eventos POST
Após a verificação, o Meta faz uma requisição POST com o evento:
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { ... }, "messages": [{ "from": "521234567890", "id": "wamid.xxxxx", "timestamp": "1716000000", "text": { "body": "Olá, quanto custa?" }, "type": "text" }] }, "field": "messages" }] }] }
Seu servidor deve:
app.post('/webhooks/whatsapp', (req, res) => { const entry = req.body.entry[0].changes[0].value; if (entry.messages) { for (const msg of entry.messages) { processIncomingMessage(msg); } } if (entry.statuses) { for (const status of entry.statuses) { updateMessageStatus(status); } } res.sendStatus(200); // CRÍTICO: responda 200 rapidamente });
Etapa 4: Configurar o webhook no aplicativo Meta
No painel de controle do aplicativo Meta:
- WhatsApp → Configuração → Webhook.
- URL de retorno de chamada:
https://tu-dominio.com/webhooks/whatsapp. - Verificar Token: A string que seu código compara.
- Inscrever-se nos campos:
mensagens,atualização_de_status_do_modelo_de_mensagem, etc. - Clique Verificar e salvarSe o seu aperto de mãos funcionar, ele será gravado.
Etapa 5: Validar a assinatura de segurança
Cada POST é meta-assinado com HMAC-SHA256. A assinatura é validada para evitar solicitações fraudulentas.
const crypto = require('crypto');
function verifySignature(req) {
const signature = req.headers['x-hub-signature-256'];
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.WHATSAPP_APP_SECRET)
.update(JSON.stringify(req.body))
.digest('hex');
return signature === expected;
}
Tratamento de erros e novas tentativas
O Meta tenta novamente o POST se o seu servidor:
- Retorna um código diferente de 200.
- Ele/Ela não responde em 5 segundos.
Boas práticas:
- Responda 200 imediatamente e processa a lógica em segundo plano com uma fila.
- Idempotência. Cada evento tem um
wamidúnico — se você receber duplicados, não processe duas vezes. - Registro Carga útil completa recebida para depuração.
- Alertas se a taxa de erro aumentar.
Erros comuns na configuração de webhooks
- HTTP em vez de HTTPS — Meta rejeita.
- Certificado SSL inválido — O Meta valida a cadeia de certificados.
- Verificar token incorreto — aperto de mãos falha.
- Lógica do processo antes de retornar 200 — Tempo limite, Meta recua.
- Não validar assinatura — risco de pedidos falsos.
- Não processe duplicados. — você processa o mesmo evento duas vezes.
A alternativa sem código: Aurora Inbox
Para 9 em cada 10 PMEs, configurar webhooks diretamente é um processo excessivamente complexo. O Aurora Inbox absorve toda essa complexidade:
- Webhook configurado e mantido pelo Aurora Inbox.
- Processando mensagens recebidas com agente de IA pronto.
- As atualizações de status são acompanhadas no painel de controle.
- Modelos gerenciados na interface do usuário sem usar a API.
- Monitoramento da qualidade dos números com alertas precoces.
Se você precisa de extensibilidade, o Aurora Inbox expõe sua própria API REST, onde você pode se inscrever em eventos do aplicativo que são mais úteis do que os eventos brutos do Meta:
conversa.criadaconversa.atribuídaai_agent.escaladolíder qualificadoacordo.fase_alterada
Comece seu teste gratuito e conectar o WhatsApp sem acessar webhooks brutos.
Tabela comparativa
| Aspecto | Webhook bruto API da Nuvem | Caixa de entrada Aurora |
|---|---|---|
| Tempo de implementação | 1 a 3 semanas | 10 minutos |
| Manutenção contínua | 5 a 15 horas por mês | 0 |
| HTTPS / SSL | Sua responsabilidade | Manuseado |
| Validação de assinatura | Sua responsabilidade | Manuseado |
| Tentativas / idempotência | Sua responsabilidade | Manuseado |
| Processamento de carga útil | Sua responsabilidade | Feito |
| Webhooks de aplicativos | Faça você mesmo | Disponível |
Por que a Aurora Inbox?
O Aurora Inbox absorve a complexidade dos webhooks do WhatsApp Business e expõe webhooks de aplicativos de nível superior para suas integrações. Ele combina um BSP de meta-nível, agente LLM, RAG, suporte multicanal e uma API REST completa para extensibilidade.
Comece seu teste gratuito e deixa para trás a complexidade dos webhooks brutos.
Perguntas frequentes
Preciso de um servidor para usar webhooks do WhatsApp?
Para uma API direta na nuvem, sim. Para uma plataforma como o Aurora Inbox, não — a plataforma gerencia o webhook.
Quanto tempo leva para configurar um webhook bruto?
De 1 a 3 semanas para uma implementação produtiva com segurança e novas tentativas. Aurora Inbox: 10 minutos.
Que eventos a Meta envia via webhook?
mensagens, status, atualização_de_status_do_modelo_de_mensagem, atualização_de_capacidade_de_negócios, atualização_de_qualidade_do_número_de_telefone.
Preciso de um HTTPS válido para webhooks?
Sim. O Meta rejeita HTTP e certificados SSL inválidos.
Como faço para evitar o processamento de mensagens duplicadas?
Cada mensagem tem um wamid Único. Salva IDs processados e rejeita duplicados.
Posso ter vários webhooks para o mesmo número?
Não diretamente na API da nuvem. O método padrão é ter um único webhook que encaminha para vários destinos internos.
