> ## Documentation Index
> Fetch the complete documentation index at: https://docs.watahub.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Verifica firmas y gestiona entregas duplicadas de forma segura.

## Elige el alcance

Usa `POST /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 son `X-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. Guarda `X-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.