O que é um webhook, na prática
Webhook é um endereço na internet (uma URL) que fica esperando ser chamado. Você registra esse endereço na Meta e diz: "quando acontecer alguma coisa com o meu número de WhatsApp, avisa aqui". A partir daí, sempre que rola um evento, a Meta dispara uma requisição para essa URL com os detalhes do que aconteceu.
A grande sacada é a inversão do fluxo. Sem webhook, o seu sistema teria que ficar batendo na porta da Meta o tempo todo, perguntando se chegou mensagem nova — um desperdício de recurso que ainda por cima atrasa a resposta. Com webhook, é a Meta que bate na sua porta no instante em que o evento ocorre. Por isso costumam dizer que webhook é o oposto de uma API comum: aqui é o servidor deles que chama o seu.
O que o webhook do WhatsApp notifica
Na Cloud API, os avisos se dividem basicamente em dois grupos. Um cuida de mensagens que chegam; o outro, do que acontece com as mensagens que você mandou. Saber diferenciar os dois evita muita confusão na hora de montar o atendimento.
| Tipo de notificação | O que dispara | Onde aparece no payload |
|---|---|---|
| Mensagem recebida (inbound) | Um cliente te envia texto, áudio, foto, botão, etc. | value.messages[] |
| Status de entrega | A mensagem que você enviou foi enviada, entregue, lida ou falhou | value.statuses[] |
| Status de template | Um modelo de mensagem foi aprovado, rejeitado ou pausado pela Meta | changes[] com campo de template |
| Qualidade e limites | Mudança na quality rating ou no tier de disparo do número | changes[] de conta/telefone |
Como o webhook é configurado (a verificação)
Antes de mandar qualquer evento, a Meta precisa ter certeza de que aquela URL é mesmo sua. Esse aperto de mão acontece uma vez, no cadastro, e segue sempre o mesmo roteiro.
Você informa dois dados no painel: a URL de callback e um verify token — uma senha que você inventa. A Meta então faz uma requisição GET para a sua URL com três parâmetros: hub.mode (sempre "subscribe"), hub.verify_token (que precisa bater com a senha que você cadastrou) e hub.challenge (um valor aleatório). O seu sistema confere se o token confere e devolve o challenge de volta. Deu certo? A partir daí a Meta passa a enviar os eventos de verdade, agora como requisições POST.
- A URL de callback precisa ser HTTPS e pública — a Meta exige isso até em ambiente de teste.
- O verify token é escolhido por você e serve só para o aperto de mão inicial; não é chave de segurança do conteúdo.
- Na validação a Meta usa GET; nos eventos reais, usa POST. Seu endpoint precisa responder aos dois.
- Cada tipo de aviso depende de uma permissão: whatsapp_business_messaging para mensagens e whatsapp_business_management para os demais.
Por que webhook importa mesmo se você não programa
Talvez você nunca vá escrever uma linha de código para isso — e tudo bem. A maioria das empresas acessa a API oficial por meio de um BSP ou de uma plataforma de atendimento, e é ela quem cuida do webhook por baixo dos panos. Ainda assim, entender o conceito ajuda a diagnosticar problema.
Quando o atendimento "não recebe as mensagens" ou o painel mostra tudo como enviado mas nada como entregue, quase sempre é o webhook que caiu ou foi configurado errado. É ali que a informação de status de entrega e leitura chega. Sem webhook funcionando, você fica no escuro: manda mensagem e não sabe se ela foi lida, se falhou ou se o cliente respondeu.
Perguntas frequentes
Webhook do WhatsApp é a mesma coisa que a API?
Preciso de webhook para usar o WhatsApp Business API?
O que é o verify token do webhook?
Por que meu webhook parou de receber mensagens?
- Meta for Developers — WhatsApp Business Cloud API Webhooks Setup
- Hookdeck — Guide to WhatsApp Webhooks: Features and Best Practices
- AiSensy — Webhooks do WhatsApp para Não Desenvolvedores (Guia)
- Anjok Technologies — WhatsApp Cloud API Webhook Setup Explained (2026)
- Hooklistener — WhatsApp Webhooks: Cloud API Setup, Verify Token & Testing
Termos relacionados
O que é WhatsApp Cloud API: Diferença da API Clássica
WhatsApp Cloud API é a versão da API oficial hospedada pela Meta. Entenda como funciona, a diferença para a antiga On-Premises e quanto custa por mensagem.
Ler →
WhatsApp Business API
O que é WhatsApp Business API, como funciona, quem pode usar, diferença em relação ao WhatsApp Business App e o papel dos BSPs (Business Solution Providers) certificados pela Meta.
Ler →
API Oficial do WhatsApp: Como Contratar, Quanto Custa e Por Onde Começar (2026)
Guia completo para contratar a API oficial do WhatsApp (WhatsApp Business Platform) em 2026: o que é, como verificar a empresa, quem são os BSPs, custos reais e diferença entre Cloud API e On-Premises.
Ler →
Rate Limit no WhatsApp Business API
Rate limit no WhatsApp Business API é o teto de velocidade (MPS) e de chamadas de API que a Meta impõe. Entenda a diferença para o limite de mensagens e como aumentar.
Ler →
Como Criar Template Aprovado no WhatsApp Business (Guia 2026)
Seu template do WhatsApp Business API vive sendo reprovado? Veja o passo a passo para escolher a categoria certa, formatar as variáveis e escrever um texto que a Meta aprova de primeira.
Ler →