Pular para o conteúdo principal

Feature - Webhook Meta (Inbound e Verificação)

Introdução ao documento​

Este documento descreve a feature de webhook da Meta para verificação inicial e tratamento de mensagens recebidas. Evidência: src/routes/webhook.ts:10 Evidência: src/routes/webhook.ts:83

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:16

Referencial teórico​

  • Endpoint de verificação GET /webhook.
  • Processamento de eventos em POST /webhook. Evidência: src/routes/webhook.ts:83 Evidência: src/routes/webhook.ts:10

Visão geral​

A feature valida o webhook no setup da Meta e processa mensagens recebidas, respondendo automaticamente em casos de texto e marcando mensagem como lida. Evidência: src/routes/webhook.ts:89 Evidência: src/routes/webhook.ts:19 Evidência: src/routes/webhook.ts:54

Atores​

  • Plataforma Meta/WhatsApp (envia eventos e challenge).
  • Serviço dhedalos-api-onboarding-express.
  • Usuário final remetente da mensagem. Evidência: src/routes/webhook.ts:16 Evidência: src/routes/webhook.ts:29 Evidência: src/routes/webhook.ts:38

Pré-condições​

  • WEBHOOK_VERIFY_TOKEN configurado para validação no GET /webhook.
  • WHATSAPP_API_TOKEN para respostas automáticas na Graph API.
  • Payload com estrutura de entry/changes/value/messages para tratamento de texto. Evidência: src/routes/webhook.ts:89 Evidência: src/routes/webhook.ts:20 Evidência: src/routes/webhook.ts:16

Fluxo principal​

  1. Meta envia evento em POST /webhook.
  2. Serviço extrai mensagem.
  3. Se for texto, envia resposta automática.
  4. Marca mensagem como lida.
  5. Retorna 200. Evidência: src/routes/webhook.ts:10 Evidência: src/routes/webhook.ts:16 Evidência: src/routes/webhook.ts:28 Evidência: src/routes/webhook.ts:54 Evidência: src/routes/webhook.ts:75

Fluxos alternativos​

  • GET /webhook retorna challenge quando token confere.
  • GET /webhook retorna 403 quando token diverge.
  • POST /webhook sem mensagem de texto não envia resposta, mas retorna 200. Evidência: src/routes/webhook.ts:91 Evidência: src/routes/webhook.ts:95 Evidência: src/routes/webhook.ts:19 Evidência: src/routes/webhook.ts:75

Regras de negócio​

  • Somente mensagens type=text entram no fluxo de resposta automática.
  • Resposta usa texto fixo orientando suporte em URL específica.
  • Todas as mensagens processadas recebem tentativa de marcação como lida. Evidência: src/routes/webhook.ts:19 Evidência: src/routes/webhook.ts:40 Evidência: src/routes/webhook.ts:63

Estados possíveis (quando houver)​

  • Webhook verificado (200 no GET).
  • Webhook não autorizado (403 no GET).
  • Evento processado (200 no POST). Evidência: src/routes/webhook.ts:91 Evidência: src/routes/webhook.ts:95 Evidência: src/routes/webhook.ts:75

Endpoints envolvidos​

Dados impactados​

  • Não há persistência local; operações são integrações outbound para Graph API.
  • Referência de dados locais: ../data/model.md. Evidência: src/routes/webhook.ts:29 Evidência: src/routes/webhook.ts:55

Pendências​

  • Confirmar se o payload de eventos não-texto deve ter tratamento dedicado. Evidência: src/routes/webhook.ts:19 Evidência: src/routes/webhook.ts:75