Elige el alcance
UsaPOST /v1/project-webhooks para whatsapp.phone_number.created y whatsapp.phone_number.disconnected.
Usa POST /v1/phones/{phoneNumberId}/webhooks para whatsapp.message.received, whatsapp.message.sent, whatsapp.message.delivered, whatsapp.message.read y whatsapp.message.failed.
Ambos aceptan url HTTPS pública, secret (32–512 caracteres), events y active opcional. Guarda el secreto de forma segura. La referencia incluye consulta, actualización y eliminación.
Verifica cada entrega
Los headers sonX-Webhook-Event, X-Webhook-Signature y X-Idempotency-Key. La firma es el HMAC-SHA256 hexadecimal del cuerpo original exacto con tu secreto, sin prefijo sha256=.
Lee los bytes originales antes de interpretar el JSON. Calcula el HMAC, compara en tiempo constante y rechaza firmas inválidas. Volver a serializar el JSON puede alterar los bytes e invalidar la firma.
Gestiona reintentos
La entrega es al menos una vez. GuardaX-Idempotency-Key de forma persistente para no repetir acciones. Responde 2xx tras aceptar el evento de forma segura y procesa el trabajo costoso de manera asíncrona. No presupongas tiempos fijos de reintento ni orden garantizado.
El destino administrativo antiguo usa otros headers. No uses su x-watahub-delivery-id en tu receptor de webhooks de desarrollador.