Um webhook permite que a integração receba notificações de mensagens e estados da plataforma. Configurar o endereço no painel é apenas uma parte: o serviço também precisa de validar a origem, tratar duplicações e acompanhar falhas. Este guia fornece um roteiro defensivo, sem credenciais, dados de clientes ou uma versão de API fixada sem confirmação.
Pré-requisitos
Confirme aplicação, conta, permissões e recursos oficiais necessários à integração escolhida. Use um endpoint HTTPS acessível à plataforma e um ambiente apropriado para conferir a configuração. Segredos de aplicativo e tokens pertencem ao armazenamento privado autorizado, não ao código público, URL ou log.
Cinco etapas de configuração
- Definir eventos: listar mensagens e estados que o processo realmente precisa, consultando a referência vigente.
- Preparar o endpoint: separar verificação da inscrição de processamento de notificações.
- Validar a origem: conferir o mecanismo oficial de assinatura sobre o corpo recebido antes de processar dados.
- Registrar a inscrição: confirmar os recursos e campos necessários no painel e na documentação da versão utilizada.
- Conferir o caminho completo: usar recursos autorizados para observar recebimento, processamento e resultado no sistema de destino.
O SDK oficial da Meta documenta a verificação GET com hub.verify_token e resposta com hub.challenge, além da validação de x-hub-signature-256. O repositório informa que o projeto foi arquivado; use essa referência para compreender os mecanismos e confirme a implementação atual na documentação principal antes de instalar um SDK.
Receber não é concluir uma operação
Separe a aceitação da notificação do trabalho de negócio. Um evento recebido pode exigir uma tarefa em fila e uma confirmação posterior. Registrar o código de resposta HTTP não comprova que uma marcação, entrega ou atualização de CRM foi concluída.
Trate reentrega e duplicação com um identificador adequado do evento ou mensagem e uma regra de idempotência. O mesmo aviso não deve criar duas reservas ou enviar duas respostas. Defina como recuperar uma falha sem repetir operações que já terminaram.
Modelo de diagnóstico sem conteúdo pessoal
| Sintoma | Verificação proposta |
|---|---|
| Inscrição não confirma | Rota, HTTPS e parâmetros da verificação oficial. |
| Inscrição confirma, evento não chega | Recursos inscritos, campo e configuração da aplicação. |
| Evento chega, tarefa não termina | Fila, dependência, estado e erro de processamento. |
| Operação duplicada | Identificador e deduplicação antes do efeito no sistema. |
Registre horário, tipo, identificador técnico apropriado e resultado, com acesso e retenção definidos. Evite corpo integral, telefone, tokens ou assinaturas em logs públicos. Exemplos de desenvolvimento devem usar dados sintéticos.
Critérios de conclusão
Documente a versão consultada, eventos necessários, validação, duplicação, falha e reprocessamento. As páginas técnicas específicas da Meta não estavam acessíveis nesta revisão; confira-as antes de colocar uma implementação em produção. Este roteiro não afirma que uma integração real tenha sido instalada ou verificada.
Leituras complementares
- vários números no WhatsApp
- fila de envio da API oficial
- Meta for Developers — Create a webhook endpoint
- Meta for Developers — messages webhook reference
- Twilio — Overview of the WhatsApp Business Platform
