> ## 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

> Verify signatures and handle duplicate deliveries safely.

## Choose the scope

Use `POST /v1/project-webhooks` for `whatsapp.phone_number.created` and `whatsapp.phone_number.disconnected`.

Use `POST /v1/phones/{phoneNumberId}/webhooks` for `whatsapp.message.received`, `whatsapp.message.sent`, `whatsapp.message.delivered`, `whatsapp.message.read` and `whatsapp.message.failed`.

Both accept public HTTPS `url`, `secret` (32–512 characters), `events` and optional `active`. Store the secret securely. The reference includes list, update and delete operations.

## Verify each delivery

Headers are `X-Webhook-Event`, `X-Webhook-Signature` and `X-Idempotency-Key`. The signature is the hex HMAC-SHA256 of the exact raw body using your webhook secret, **without** a `sha256=` prefix.

Read raw bytes before JSON parsing. Compute the HMAC, compare in constant time and reject invalid signatures. Reserializing JSON can change bytes and invalidate the signature.

## Handle retries

Delivery is at least once. Persist `X-Idempotency-Key` to avoid repeating business actions. Acknowledge with `2xx` after safely accepting the event, then process expensive work asynchronously. Do not assume fixed retry timing or guaranteed event order.

The older administrative subscriber destination uses different headers. Do not use its `x-watahub-delivery-id` in your developer webhook handler.


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