API reference / Notifications

post/v2/webhooks/whatsapp

WhatsApp delivery receipts and inbound replies

Operation
whatsAppEventWebhook
Authentication
None — public

Called by Meta, not by partners. **Unauthenticated** — Meta cannot present a Haavisa API key, so the body is authenticated by the `X-Hub-Signature-256` header instead: HMAC-SHA256 over the **raw** request body, keyed by the app secret. Meta signs an escaped-unicode rendering, so the bytes are hashed exactly as they arrived rather than re-serialised — which is why this route keeps the body as a string. Meta signs no timestamp, so a captured delivery can be replayed; the defence is that applying a status is idempotent, not a replay window.

One subscription carries both kinds of event. `statuses[]` moves `delivery_status` and `delivered_at` on the notification the `wamid` belongs to, matching on provider *and* ref because the same column holds the email provider’s message ids. `messages[]` are replies from the applicant, and only the fact of them is recorded — a masked number and the message type. The body is deliberately neither stored nor logged.

Everything genuine is answered 200, including a status for a message this system does not hold: Meta retries a non-200 with decreasing frequency for up to seven days, and an old event is ordinary rather than an error. Without `META_APP_SECRET` the route answers 503 and refuses everything.

Request

Responses

200Received. `statuses` and `inbound` count what the payload carried, `matched` how many receipts found a notification.
receivedbooleanrequired
statusesintegerrequired
matchedintegerrequired
inboundintegerrequired
400The body is not JSON, or is empty.
errorobjectrequired
401The signature is missing, malformed, or does not match.
errorobjectrequired
503`META_APP_SECRET` is not set, so nothing can be verified.
errorobjectrequired

Example

curl
curl -X POST https://api.haavisa.com/v2/webhooks/whatsapp

More in Notifications

Something unclear? The eligibility guide explains the model behind the answers; the errors guide covers the envelope.