Webhooks

Você não configura callback nenhum na Meta. Nós recebemos todos os eventos das contas conectadas, validamos a assinatura da Meta e reentregamos para os endpoints que você cadastrar.

O corpo da entrega

É o envelope da Meta, byte a byte. Handlers já escritos para a Cloud API funcionam sem alteração.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "111222333444555",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5541987111527",
              "phone_number_id": "106540352242922"
            },
            "messages": [
              {
                "from": "5541999999999",
                "id": "wamid.HBgNNTU0MTk5OTk5OTk5OQ...",
                "timestamp": "1785312000",
                "type": "text",
                "text": { "body": "Oi, chegou meu pedido?" }
              }
            ]
          }
        }
      ]
    }
  ]
}

Headers de cada entrega

Header	Conteúdo
X-Joinotify-Signature-256	sha256=<hex> — HMAC da entrega
X-Joinotify-Timestamp	Unix em segundos, incluído no HMAC
X-Joinotify-Event	Nome do evento, ex. messages
X-Joinotify-Delivery	ID da entrega, estável entre as retentativas
User-Agent	Joinotify-Webhook/1.0

Três regras que evitam a maioria dos problemas

Responda 2xx primeiro, processe depois. O timeout é de 20 segundos. Um handler que grava no banco, chama três APIs e só então responde vai estourar em produção.

Valide a assinatura sobre o corpo bruto. Se você deixar o framework parsear o JSON antes, a assinatura nunca vai bater.

Seja idempotente. Uma entrega pode ser repetida. Deduplique pelo X-Joinotify-Delivery ou pelo wamid da mensagem.

Por onde seguir

• Configurar — cadastrar, filtrar e testar endpoints.
• Verificar assinatura — o HMAC, com exemplos em Node, Python e PHP.
• Catálogo de eventos — os 20 eventos e o que cada um traz.
• Entrega e retentativas — timeouts, backoff e o log de entregas.