Webhooks Avancados: Eventos e Payloads da API

Estrutura do Payload

Todo webhook da API do WhatsApp segue uma estrutura padrao com entry, changes e value:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "551199999999", "phone_number_id": "PHONE_ID" },
        "contacts": [{ "profile": { "name": "Cliente" }, "wa_id": "5511888888888" }],
        "messages": [{ "id": "wamid.xxx", "from": "5511888888888", "timestamp": "1697000000", "type": "text", "text": { "body": "Ola!" } }]
      }
    }]
  }]
}

Eventos de Mensagem

Os principais tipos de mensagem que voce pode receber:

• text: Mensagem de texto simples
• image/video/audio/document: Midia com ID para download
• location: Coordenadas GPS compartilhadas
• contacts: Cartao de contato
• interactive: Resposta a botao ou lista
• button: Resposta a template com botao
• reaction: Reacao com emoji a uma mensagem
• sticker: Figurinha
• order: Pedido do catalogo

Eventos de Status

Acompanhe o ciclo de vida de cada mensagem enviada:

• sent: Mensagem entregue ao servidor do WhatsApp
• delivered: Mensagem entregue ao dispositivo do destinatario
• read: Destinatario visualizou a mensagem
• failed: Falha na entrega com codigo de erro

Tratamento de Erros

Eventos de falha incluem codigos de erro detalhados:

• 131047 — Mensagem nao entregue dentro de 24h (expirada)
• 131026 — Mensagem bloqueada por politica
• 131051 — Tipo de mensagem nao suportado
• 130472 — Numero nao registrado no WhatsApp

Processamento Resiliente

A regra de ouro dos webhooks: responda rapido (200 OK) e processe depois. Nunca faca operacoes demoradas no handler do webhook.

1. Receba o webhook e responda 200 imediatamente
2. Publique o evento em uma fila de mensagens
3. Workers consomem a fila e processam cada evento
4. Eventos que falham vao para dead letter queue para analise

Conclusao

Um processamento de webhooks robusto e a base de qualquer integracao profissional com o WhatsApp. Entenda cada tipo de evento, implemente idempotencia e use filas para garantir que nenhuma mensagem seja perdida.