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

> Verifique assinaturas e trate entregas duplicadas com segurança.

## Escolha o escopo

Use `POST /v1/project-webhooks` para `whatsapp.phone_number.created` e `whatsapp.phone_number.disconnected`.

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

Ambos aceitam `url` HTTPS pública, `secret` (32–512 caracteres), `events` e `active` opcional. Guarde o segredo com segurança. A referência inclui consulta, atualização e exclusão.

## Verifique cada entrega

Os headers são `X-Webhook-Event`, `X-Webhook-Signature` e `X-Idempotency-Key`. A assinatura é o HMAC-SHA256 hexadecimal do corpo original exato com seu segredo, **sem** prefixo `sha256=`.

Leia os bytes originais antes de interpretar o JSON. Calcule o HMAC, compare em tempo constante e rejeite assinaturas inválidas. Serializar o JSON novamente pode alterar os bytes e invalidar a assinatura.

## Trate novas tentativas

A entrega ocorre pelo menos uma vez. Armazene `X-Idempotency-Key` de forma persistente para não repetir ações. Responda `2xx` após aceitar o evento com segurança e processe tarefas demoradas de forma assíncrona. Não presuma intervalos fixos de novas tentativas nem ordem garantida.

O destino administrativo legado usa outros headers. Não use seu `x-watahub-delivery-id` no receptor de webhooks de desenvolvedor.


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