Webhook da Cloud API: como chega a mensagem, como chega o status de entrega e por que o evento se perde
A documentação da Meta atualizada em 21 de maio de 2026 confirma o ponto que mais dói na operação: não existe API para buscar histórico de webhook. O que o seu servidor não capturou no momento do envio está perdido, e a Meta só tenta reentregar por 7 dias.
Como o WhatsApp entrega uma mensagem ao seu sistema?
Por webhook. A Meta faz uma requisição HTTP POST, com corpo em JSON, para um endpoint público que você registrou. Não é o seu sistema que vai buscar a mensagem: é o servidor da Meta que empurra o evento. A documentação oficial da plataforma é explícita ao dizer que o conteúdo de qualquer mensagem enviada por um usuário do WhatsApp para o seu número de negócio é comunicado por webhook, e que todos os status de entrega das mensagens que você envia também são reportados por webhook.
Essa é a frase que define a arquitetura de qualquer operação séria no canal. O webhook não é um recurso acessório de notificação. Ele é a única porta de entrada da conversa. Se o endpoint estiver fora do ar, a conversa continua acontecendo do lado do cliente e simplesmente não existe do lado da empresa.
O agravante está em uma linha curta da referência de endpoint: não há APIs para buscar dados históricos de webhook, então capture e armazene os payloads de acordo. Traduzindo para a operação: não existe botão de reprocessar a semana passada. O evento perdido é perdido.
Por que o webhook não chega?
A própria documentação lista as causas mais comuns, e nenhuma delas é exótica. Vale conferir nesta ordem antes de abrir chamado com o fornecedor:
- O endpoint não está aceitando requisições, ou o certificado está inválido. A Meta exige TLS ou SSL válido e corretamente instalado, e não aceita certificado autoassinado.
- O aplicativo está em modo de desenvolvimento. Alguns webhooks não são enviados enquanto o app não está em modo Live.
- A verificação inicial falhou. Toda vez que você altera o campo de Callback URL ou o Verify token, a Meta dispara um GET com
hub.mode,hub.challengeehub.verify_token. Se o seu servidor não devolver HTTP 200 com o valor exato dehub.challenge, o endpoint é considerado não verificado e nenhum webhook é enviado. - A assinatura da requisição não foi validada e o payload foi descartado pelo seu próprio código. Cada POST vem com o cabeçalho
X-Hub-Signature-256, um hash HMAC-SHA256 calculado sobre o corpo da requisição usando o app secret como chave. - O campo de webhook nunca foi assinado. Receber mensagem depende de assinar o campo
messages. Saber que um template foi reprovado depende demessage_template_status_update. São assinaturas separadas, no painel de configuração do app.
Há ainda um limite de tamanho que costuma passar despercebido: o payload de webhook pode chegar a 3 MB. Servidor com limite de corpo de requisição menor do que isso rejeita silenciosamente o evento e devolve erro, o que joga a mensagem para a fila de retentativa.
Quais status de entrega existem e o que cada um significa?
O mesmo campo messages transporta duas coisas diferentes: a mensagem que o usuário enviou e o status da mensagem que a empresa enviou. Os valores de status são cinco, segundo a referência oficial.
| Status | O que significa | Equivalente na tela do WhatsApp |
|---|---|---|
sent | A mensagem saiu dos servidores da Meta | Um tique |
delivered | Chegou ao aparelho do usuário | Dois tiques |
read | Foi exibida em uma conversa aberta no aparelho | Dois tiques azuis |
played | Primeira reprodução de uma mensagem de voz | Microfone azul |
failed | Falha ao enviar ou ao entregar | Triângulo vermelho |
Um detalhe quebra relatório de quem calcula taxa de entrega ingenuamente: quando o usuário recebe a mensagem já com a conversa aberta na tela, o evento delivered não é enviado. A documentação chama isso de otimização interna e explica que a entrega fica implícita, porque a mensagem foi lida. Quem soma apenas delivered subestima a entrega real.
Só o status failed traz o objeto errors, com código, título e detalhe. E só os status sent combinados com delivered ou read trazem o objeto pricing, que informa se a mensagem é cobrável, o modelo de precificação aplicado e a categoria. É desse objeto, e não de uma estimativa, que sai a conciliação de custo por mensagem.
Por que o mesmo evento chega duas vezes?
Por desenho. Se o seu endpoint devolver qualquer coisa diferente de HTTP 200, ou se o webhook não puder ser entregue por outro motivo, a entrega é repetida imediatamente e depois com frequência decrescente ao longo de até 7 dias. Respostas não reconhecidas são descartadas depois desse prazo.
O ponto que gera duplicidade está na frase seguinte da documentação: as retentativas são enviadas a todos os aplicativos inscritos nos webhooks daquela conta do WhatsApp Business, o que pode resultar em notificações duplicadas. Some a isso o fato de que os POSTs são agregados em lotes de até 1000 atualizações, sem garantia de que virão agrupados. A conclusão prática é explícita no texto oficial: o seu servidor deve tratar deduplicação.
Na prática, isso significa gravar o identificador da mensagem (wamid) com restrição de unicidade no banco antes de processar qualquer regra de negócio. Sem isso, uma retentativa vira um segundo lead, um segundo card no funil ou uma segunda cobrança disparada.
O que muda para quem opera atendimento no Brasil
Três decisões de arquitetura deixam de ser opcionais em qualquer operação que dependa do canal para vender ou atender. A primeira é gravar o payload cru antes de interpretar qualquer coisa. Como não existe histórico do lado da Meta, o log do seu receptor é a única fonte de verdade em auditoria de conversa.
A segunda é responder 200 rápido e processar depois, em fila. Endpoint que faz consulta pesada em banco antes de responder acumula timeout, entra na fila de retentativa e passa a receber eventos duplicados justamente no pico.
A terceira é usar o campo biz_opaque_callback_data no envio. É uma string livre, definida por você, que volta no webhook de status. É o jeito documentado de amarrar o status de entrega ao registro do seu CRM sem depender de tabela de correspondência frágil. Quem está montando esse tipo de fluxo encontra o desenho completo do canal no nosso guia da API oficial do WhatsApp e o passo a passo de operação em como automatizar atendimento no WhatsApp.
Leitura crítica
O modelo de webhook da Meta é convencional e funciona bem, mas transfere para a empresa um risco que muita operação não dimensiona: a durabilidade do dado. Plataformas de mensageria costumam vender o webhook como detalhe técnico do fornecedor, e o cliente descobre o custo real só quando precisa reconstituir uma conversa de três meses atrás e não existe de onde puxar.
A ausência de API de histórico é uma escolha da Meta, não uma limitação técnica. Ela reduz custo de armazenamento do lado da plataforma e empurra a responsabilidade para a ponta. Quem contrata um intermediário deveria perguntar, antes de assinar, por quanto tempo o payload cru fica armazenado e se é exportável. Essa resposta vale mais do que qualquer painel bonito de atendimento.