# Webhook do WhatsApp API: como as respostas e os status chegam ao seu sistema

> O webhook WhatsApp API é o endereço do seu sistema para onde a Meta envia, em tempo real, as respostas dos clientes e os status de cada mensagem (enviada, entregue, lida ou com falha). Sem webhook, o disparo sai, mas ninguém vê o retorno. Quando a AD PRO dispara pela API oficial, as respostas seguem para o seu time, o seu CRM ou o fluxo combinado.

Página original: https://www.adprotecnologia.com.br/disparo-em-massa/webhook-do-whatsapp-api
Autor: AD PRO Tecnologia. Publicado em 2026-10-31.

## O que é o webhook da API do WhatsApp e para que serve?

Webhooks são requisições HTTP com conteúdo em JSON que os servidores da Meta enviam para um endereço que você define. Na API do WhatsApp, o campo **messages** cobre dois tipos de aviso: as mensagens que os clientes mandam para a empresa e as atualizações de status das mensagens que a empresa enviou. Em vez de perguntar à Meta o tempo todo se algo mudou, o seu sistema é avisado quando acontece.

Para o disparo em massa, isso resolve duas coisas. A primeira é o **atendimento**: a resposta do cliente chega ao CRM e cai na fila de quem vai atender. A segunda é a **medição**: cada mensagem recebe um status, e a soma dos status vira o relatório da campanha. Se você quer entender o conceito de webhook em geral, veja [o que é webhook](https://www.adprotecnologia.com.br/crm/blog/o-que-e-webhook); aqui o foco é o WhatsApp.

## O que a Meta envia pelo webhook?

No caminho de saída, cada mensagem enviada gera avisos de status. Segundo a documentação da Meta, os valores são estes:

**Status de mensagem enviados pelo webhook do WhatsApp**

| Status | O que significa | Como usar no disparo |
| --- | --- | --- |
| sent | A mensagem saiu dos servidores com sucesso | Conta como envio, ainda não prova entrega |
| delivered | A mensagem chegou ao aparelho do cliente | Base do relatório de entrega |
| read | A mensagem foi exibida em uma conversa aberta | Indica leitura; se o cliente viu com o chat aberto, o aviso de entregue pode ser pulado |
| failed | Falha ao enviar ou entregar | Vem com código de erro; separar por motivo antes de reenviar |

Cada aviso traz o identificador da mensagem, o status, o horário, o número do destinatário e, quando há falha, um bloco de erro com código e descrição. Um dos avisos (sent, delivered ou read) também traz o bloco de cobrança, com a categoria da mensagem. Um detalhe útil para campanhas: se você enviar um valor próprio de controle junto com a mensagem (o campo de dados opacos de retorno), ele volta no status. Dá para carregar ali o código da campanha e cruzar o resultado com a sua planilha depois.

O seu sistema precisa aceitar que o entregue não chegue: quando a mensagem é lida no instante em que chega, a Meta manda só o lido. Também precisa aceitar avisos repetidos, por causa das novas tentativas descritas adiante. Para entender o que cada código de falha quer dizer, use [códigos de erro da API do WhatsApp](https://www.adprotecnologia.com.br/disparo-em-massa/codigos-de-erro-whatsapp-api) e [status de entrega da API do WhatsApp](https://www.adprotecnologia.com.br/disparo-em-massa/status-de-entrega-whatsapp-api).

O webhook também carrega avisos da conta, além das mensagens: a Meta notifica pausa de template (por webhook, e-mail e no gerenciador) e informa, quando nega o aumento de limite, o próximo passo pelo alerta de conta. Ou seja, o mesmo canal que traz a resposta do cliente traz o sinal de que algo precisa de atenção.

## Como configurar o webhook, passo a passo?

1. **Criar um endereço HTTPS.** O endpoint precisa de certificado TLS válido e bem instalado. Certificado autoassinado não é aceito. Existe a opção de mTLS para mais segurança.
2. **Responder à verificação.** A Meta faz uma requisição GET com hub.mode igual a subscribe, um hub.challenge aleatório e o seu hub.verify_token. Se o token bate com o que você guardou, responda 200 e devolva o valor do challenge. Só depois disso a Meta começa a enviar eventos.
3. **Cadastrar o endereço no painel.** No painel do app da Meta, em WhatsApp e Configuration, informe a URL de retorno (callback) e o token de verificação.
4. **Assinar os campos.** Depois da verificação, aparece a lista de campos. Marque o campo messages (respostas e status) e os campos da conta que o seu time precisa acompanhar.
5. **Validar a assinatura de cada aviso.** Cada POST traz o cabeçalho X-Hub-Signature-256 no formato sha256=hash. Calcule o HMAC-SHA256 do corpo bruto com o segredo do app e compare. Se não bate, descarte.
6. **Responder 200 e tratar depois.** Devolva 200 logo que validar e processe a fila em seguida. Resposta diferente de 200 faz a Meta tentar de novo.

> **Aplicativo em modo desenvolvimento não recebe tudo:** A Meta avisa que alguns webhooks não são enviados quando o app está em modo de desenvolvimento. Se o teste funciona e o ambiente real não, confira se o app está no modo Live.

## Quais regras técnicas o webhook precisa cumprir?

- **Repetição:** se o seu endpoint falha ou responde diferente de 200, a Meta tenta de novo por até 7 dias, com frequência decrescente. Isso gera avisos duplicados, então o tratamento precisa ser idempotente (guardar o identificador da mensagem e do status e ignorar repetidos).
- **Tamanho:** o corpo pode ter até 3 MB.
- **Lotes:** um envio pode reunir até 1.000 atualizações, mas a Meta não garante lote, então trate cada requisição como independente.
- **Permissões:** o campo messages exige a permissão whatsapp_business_messaging; os demais avisos de conta exigem whatsapp_business_management.
- **Segurança:** além da assinatura, há mTLS. A lista de IPs da Meta muda de tempos em tempos, por isso o mTLS é a opção mais estável do que liberar IP por IP.

Para testar sem perder tempo, use o envio de teste do painel do app e depois uma mensagem real para um número seu. O passo a passo de teste está em [como testar um webhook](https://www.adprotecnologia.com.br/crm/blog/como-testar-webhook).

## Como o webhook transforma o disparo em atendimento?

Quando o cliente responde, o webhook entrega a mensagem ao seu sistema, e a conversa abre a janela de 24 horas, na qual a empresa pode responder sem template (veja [janela de 24 horas do WhatsApp](https://www.adprotecnologia.com.br/crm/blog/janela-de-24-horas-do-whatsapp)). A parte que decide se a campanha vira venda é o que acontece em seguida: quem atende, em quanto tempo e com qual resposta pronta.

1. A resposta entra pelo webhook e é associada ao contato pelo número do cliente.
2. O CRM aplica a regra de fila: campanha, região ou tipo de produto.
3. O contato recebe a etiqueta da campanha, para medir depois.
4. Pedidos de saída (parar de receber) são registrados na hora e o contato sai das próximas listas.
5. Os status viram o relatório: enviadas, entregues, lidas, falhas por motivo.

Se você ainda não tem CRM, a AD PRO implementa: veja [implementação de CRM](https://www.adprotecnologia.com.br/crm/implementacao-de-crm). E para preparar o time que recebe as respostas, leia [como atender as respostas do disparo](https://www.adprotecnologia.com.br/disparo-em-massa/como-atender-as-respostas-do-disparo).

**Checklist de teste do webhook (antes da campanha)**

```text
[ ] 1. Endereço em HTTPS com certificado válido (não autoassinado)
[ ] 2. Verificação GET respondida com 200 e o challenge devolvido
[ ] 3. Campo messages assinado
[ ] 4. App no modo Live
[ ] 5. Assinatura X-Hub-Signature-256 validada (aviso com assinatura errada é descartado)
[ ] 6. Mensagem de teste enviada para um número interno: apareceram sent, delivered e read?
[ ] 7. Resposta do número interno chegou ao CRM, na fila certa?
[ ] 8. Aviso repetido (mesmo id) não duplica contato nem relatório
[ ] 9. Falha simulada (número inexistente): o erro foi gravado com código?
[ ] 10. Quem é avisado se o endpoint cair: ____________

Exemplo de campos de um aviso de status (valores fictícios):
{ id: 'wamid.EXEMPLO', status: 'delivered', timestamp: '1760000000', recipient_id: '5511999990000' }
```

> **Como a AD PRO faz:** No serviço de disparo, a parte técnica desta página (endpoint, verificação, assinatura, novas tentativas) fica com a estrutura da AD PRO. O que você decide é o destino das respostas: o seu time comercial, o seu CRM ou o fluxo combinado. E o que você recebe é o resultado já consolidado no relatório de entrega, com total enviado, entregues e evidências. Veja o [relatório de disparo em massa](https://www.adprotecnologia.com.br/disparo-em-massa/relatorio-de-disparo-em-massa).

## Perguntas frequentes

### O que é webhook na API do WhatsApp?

É uma requisição que a Meta envia para um endereço do seu sistema sempre que algo acontece: um cliente responde ou o status de uma mensagem muda. O conteúdo vem em JSON e o campo principal é o messages.

### Quais status o webhook do WhatsApp informa?

Os status de mensagem são sent (enviada), delivered (entregue), read (lida) e failed (falha). Quando há falha, o aviso vem com código e descrição do erro.

### O que acontece se meu webhook ficar fora do ar?

A Meta tenta entregar de novo por até 7 dias, com frequência decrescente. Como isso pode gerar avisos duplicados, o seu sistema precisa ignorar eventos repetidos.

### Como sei se o aviso veio mesmo da Meta?

Cada requisição traz o cabeçalho X-Hub-Signature-256. Você calcula o HMAC-SHA256 do corpo com o segredo do app e compara com o valor recebido. Se for diferente, descarte o aviso.

### Preciso configurar webhook para disparar com a AD PRO?

Não. Na estrutura da AD PRO a gente cuida disso e entrega o relatório de entrega. As respostas podem ir para o seu time ou para o seu CRM, conforme o fluxo combinado.

## Fontes

- [Meta for Developers, visão geral dos webhooks do WhatsApp](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview), conferido em 2026-10-31
- [Meta for Developers, criar um endpoint de webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint), conferido em 2026-10-31
- [Meta for Developers, referência do webhook de status de mensagens](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status), conferido em 2026-10-31
- [Meta for Developers, pausa de templates](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-pausing), conferido em 2026-10-31

---

AD PRO Tecnologia LTDA, CNPJ 68.425.611/0001-15, São Paulo/SP. Atendimento on-line para todo o Brasil. Diagnóstico comercial gratuito de 30 minutos: https://www.adprotecnologia.com.br/#agendar. WhatsApp +55 11 98604-5939. Fatos e preços publicados: https://www.adprotecnologia.com.br/fatos