Escolha o escopo
UsePOST /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ãoX-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. ArmazeneX-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.