Webhooks

No configuras ningún callback en Meta. Nosotros recibimos todos los eventos de las cuentas conectadas, validamos la firma de Meta y los reenviamos a los endpoints que registres.

El cuerpo de la entrega

Es el sobre de Meta, byte a byte. Los handlers ya escritos para la Cloud API funcionan sin cambios.

{
  "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": "Hola, ¿ya salió mi pedido?" }
              }
            ]
          }
        }
      ]
    }
  ]
}

Cabeceras de cada entrega

Cabecera	Contenido
X-Joinotify-Signature-256	sha256=<hex> — HMAC de la entrega
X-Joinotify-Timestamp	Unix en segundos, incluido en el HMAC
X-Joinotify-Event	Nombre del evento, p. ej. messages
X-Joinotify-Delivery	ID de la entrega, estable entre reintentos
User-Agent	Joinotify-Webhook/1.0

Tres reglas que evitan la mayoría de los problemas

Responde 2xx primero, procesa después. El tiempo de espera es de 20 segundos. Un handler que escribe en la base de datos, llama a tres APIs y solo entonces responde va a reventar en producción.

Valida la firma sobre el cuerpo bruto. Si dejas que el framework parsee el JSON antes, la firma nunca va a coincidir.

Sé idempotente. Una entrega puede repetirse. Deduplica por X-Joinotify-Delivery o por el wamid del mensaje.

Por dónde seguir

• Configurar — registrar, filtrar y probar endpoints.
• Verificar la firma — el HMAC, con ejemplos en Node, Python y PHP.
• Catálogo de eventos — los 20 eventos y qué trae cada uno.
• Entrega y reintentos — tiempos de espera, backoff y el registro de entregas.