Webhook no WhatsApp: como funciona

Resposta rápida (TL;DR)

Webhook é o aviso que a Meta envia ao seu sistema toda vez que algo acontece no seu número de WhatsApp: mensagem recebida, mudança de status de envio, modelo aprovado ou reprovado, alteração de nota de qualidade e de limite de envio. Em vez de o seu sistema perguntar de tempo em tempo se houve novidade, a Meta avisa sozinha, em segundos. Para funcionar, o endereço precisa ser público, com HTTPS, e responder ao teste de verificação. Duas coisas são normais e precisam estar previstas: o mesmo evento chegar duas vezes e os eventos chegarem fora de ordem.

O que é um webhook, sem termo técnico

Webhook é um endereço na internet que pertence ao seu sistema e que a Meta chama sempre que acontece algo no seu número de WhatsApp. A comparação mais direta é a de um interfone: em vez de alguém descer até a portaria a cada dez minutos para ver se chegou encomenda, a portaria toca quando chega. O seu sistema fica parado, e a Meta avisa.

Isso importa para quem contrata, e não escreve, o código por um motivo prático: quase tudo o que parece atraso, mensagem perdida ou status errado em uma operação de WhatsApp acontece dentro desse mecanismo. Saber o vocabulário evita aceitar como normal o que é falha, e evita cobrar do fornecedor o que a plataforma não promete.

Quais eventos chegam no webhook

A Meta agrupa os avisos por assunto, e cada assunto precisa ser assinado. Assinar um não traz os outros, o que explica boa parte dos casos em que a mensagem chega mas o relatório de entrega fica vazio.

Evento	O que significa	Para que a empresa usa
Mensagem recebida	Um cliente escreveu, mandou áudio, foto, documento ou clicou em um botão	Abrir atendimento, iniciar fluxo, registrar no CRM
Status de mensagem	A mensagem enviada foi aceita, entregue, lida ou falhou	Medir entrega, detectar número inválido, corrigir cadastro
Situação do modelo	Um modelo de mensagem foi aprovado, reprovado ou teve a categoria alterada	Saber que a campanha pode rodar, ou por que parou
Conta e qualidade	Mudança na nota de qualidade do número e no limite de envio	Agir antes da redução de ritmo ou da pausa do modelo

O evento de status é o mais subestimado. É ele que mostra que uma mensagem foi aceita pela Meta mas não chegou ao aparelho, diferença que muda completamente o diagnóstico. As regras de janela, categoria e limite que aparecem nesses avisos estão detalhadas no guia completo da API oficial do WhatsApp.

A verificação do endereço

Antes de mandar qualquer evento, a Meta precisa confirmar que aquele endereço é mesmo seu. A confirmação funciona assim: a Meta chama o endereço enviando um código junto com uma senha combinada (o token de verificação, escolhido por você). O seu sistema compara a senha e devolve o código de volta. Se devolver certo, a assinatura é ativada. Se não, nada é entregue.

Três condições fazem essa etapa falhar com frequência:

Endereço sem HTTPS ou com certificado vencido. A Meta não entrega evento em conexão não segura.
Endereço que não é público. Servidor local, rede interna ou ambiente atrás de senha não recebem a chamada.
Token diferente dos dois lados. Um espaço a mais no campo já quebra a comparação.

Depois de ativo, o webhook precisa responder rápido a cada chamada, confirmando que recebeu. A regra que todo desenvolvedor experiente segue é: confirmar primeiro, processar depois. Sistema que tenta gravar no banco, chamar o CRM e gerar resposta de IA antes de confirmar o recebimento acaba demorando demais e faz a Meta tratar aquilo como falha.

Reentrega e evento duplicado

Quando o seu sistema não confirma o recebimento, a Meta tenta de novo. Esse reenvio é o que impede que uma instabilidade de poucos minutos vire mensagem de cliente perdida, e é uma proteção, não um defeito.

O efeito colateral é o evento duplicado. Se o seu sistema recebeu, processou, mas demorou a confirmar, o aviso chega outra vez e o processamento se repete. Na prática isso aparece como cliente recebendo a mesma resposta automática duas vezes, chamado aberto em duplicidade ou dois registros idênticos no CRM.

A solução é sempre a mesma e cabe em uma frase para levar ao fornecedor: cada mensagem chega com um identificador único, e o sistema deve guardar os identificadores já processados e descartar repetidos. Isso se chama tratamento idempotente. Se o fornecedor não souber responder como faz isso, o problema vai aparecer no primeiro pico de volume.

A ordem de chegada não é garantida

Eventos podem chegar fora da sequência em que aconteceram. O aviso de "entregue" pode chegar antes do de "enviado", e duas mensagens seguidas do mesmo cliente podem inverter. Isso não é erro da plataforma: é consequência de um sistema distribuído tentando entregar rápido.

A consequência prática é que o seu sistema não pode confiar na ordem de chegada para decidir nada. Ele precisa olhar a marcação de tempo que vem dentro do evento e nunca rebaixar um status: se a mensagem já está como lida, um aviso atrasado de "entregue" deve ser ignorado, não sobrescrito. Fluxo automático que depende de ordem, como os descritos no guia de fluxos automáticos para suporte, precisa de um pequeno intervalo de agrupamento antes de responder, para não reagir a metade da frase do cliente.

Fila e reprocessamento

A arquitetura que sustenta volume tem duas partes separadas. A primeira só recebe o evento, guarda em uma fila e confirma. A segunda lê a fila com calma e faz o trabalho pesado: consultar cadastro, acionar IA, gravar no CRM, disparar resposta.

A vantagem aparece quando algo quebra. Se o CRM ficar fora do ar por uma hora, os eventos continuam entrando na fila e são processados depois, sem perda. Sem fila, o mesmo incidente vira uma hora de mensagens que simplesmente sumiram, e o histórico do cliente fica com buraco.

O que fazer quando o endereço cai

Queda de endpoint é questão de quando, não de se. O plano mínimo tem cinco itens, nesta ordem.

Monitoramento que avisa você, não o cliente. Alerta quando o endereço para de responder ou quando o volume de eventos cai de forma anormal.
Registro de tudo o que chegou. Guardar o evento cru antes de qualquer processamento é o que permite reconstruir depois.
Fila com reprocessamento manual. Alguém precisa conseguir mandar processar de novo o período afetado, com um comando.
Plano de recuperação da conversa. Mensagens recebidas durante a queda entram na fila de atendimento humano, com prioridade.
Atenção à janela de 24 horas. Se a queda for longa, a janela de resposta livre pode ter fechado, e a retomada passa a exigir modelo aprovado.

Esse último ponto é o que costuma escapar de quem não conhece a plataforma: o prejuízo de uma queda longa não é só o atraso, é passar a precisar de modelo aprovado para reabrir conversas que estavam livres.

Perguntas para fazer a quem vai desenvolver

Como vocês evitam processar o mesmo evento duas vezes? A resposta precisa citar identificador único guardado.
Vocês confirmam o recebimento antes ou depois de processar? A resposta correta é antes.
Existe fila? Dá para reprocessar um período? Se não houver, qualquer incidente vira perda definitiva.
Quais eventos estão assinados hoje? Faltar o de status é comum e cega o relatório.
Quem é avisado quando o endereço cai, e em quanto tempo? Sem isso, quem descobre é o cliente.

Erros comuns que custam caro

O primeiro é tratar o webhook como detalhe de implementação e não perguntar nada sobre ele na contratação. O segundo é usar o mesmo endereço para teste e produção, o que mistura evento real com simulação e corrompe relatório. O terceiro é assinar só o evento de mensagem recebida, o que deixa a operação sem enxergar falha de entrega, reprovação de modelo e queda de nota de qualidade.

O quarto é responder ao cliente direto no momento em que o evento chega, sem fila: funciona no piloto com dez conversas e trava no primeiro dia de campanha. Quem está avaliando montar integração própria ou usar plataforma pronta encontra a comparação de custo e manutenção no guia de integrações via API no WhatsApp.

Perguntas frequentes (FAQ)

O que é webhook no WhatsApp e para que serve?

É um endereço do seu sistema que a Meta chama sempre que algo acontece no seu número: mensagem recebida, status de entrega, modelo aprovado ou reprovado e mudança de nota de qualidade. Serve para o seu sistema reagir em segundos, sem ficar consultando a Meta de tempos em tempos. Sem webhook configurado, a integração só consegue enviar mensagens, nunca receber nem acompanhar o que aconteceu com elas.

Por que a mesma mensagem chega duas vezes no meu sistema?

Porque quando o seu sistema demora a confirmar o recebimento, a Meta reenvia o aviso por segurança. Isso evita perder mensagem em uma instabilidade curta, mas gera evento duplicado. A correção é guardar o identificador único que vem em cada evento e descartar os já processados. Se isso não estiver feito, o cliente recebe resposta repetida e o CRM acumula registros duplicados.

Os eventos do webhook chegam na ordem certa?

Não necessariamente. Eventos podem chegar fora da sequência em que aconteceram, inclusive um status de entrega antes do status de envio. O sistema precisa usar a marcação de tempo que vem dentro do evento e nunca rebaixar um status já registrado. Fluxos que respondem ao cliente devem esperar um pequeno intervalo de agrupamento, para não reagir a apenas parte da mensagem.

O que acontece com as mensagens se o meu servidor cair?

A Meta tenta reenviar os avisos por um período, então uma queda curta costuma ser absorvida sem perda. Em queda longa o risco é duplo: eventos que não voltam e a janela de 24 horas de resposta livre fechando, o que passa a exigir modelo aprovado para retomar a conversa. Por isso o mínimo é ter monitoramento, registro do evento cru e fila com reprocessamento.

Preciso saber programar para contratar uma integração com webhook?

Não, mas precisa saber o que exigir. Pergunte como o fornecedor evita processar o mesmo evento duas vezes, se confirma o recebimento antes de processar, se existe fila com reprocessamento, quais eventos estão assinados e quem é avisado quando o endereço sai do ar. Essas cinco perguntas separam integração que aguenta volume de integração que funciona só na demonstração.

Continue lendo

Histórico de revisões

2026-07-27 · v1.0 · publicação inicial.

Sobre as marcas mencionadas

Este portal cita marcas de terceiros para fins editoriais e comparativos. Todas as marcas são propriedade de seus respectivos donos e não possuem vínculo formal com este site. Os dados apresentados foram coletados de fontes públicas e podem mudar. Em caso de erro factual, escreva para contato@botaihub.com.br.