WhatsApp Cloud API Webhooks: Payloads, Statuses and Security

Webhooks are how the WhatsApp Cloud API talks back to you: every incoming message and every status change of a message you sent (sent, delivered, read, failed) arrives as an HTTPS POST to your server. You verify the endpoint once, check each request’s `X-Hub-Signature-256` signature, reply 200 quickly, and process the event in the background.

Meta retries failed deliveries for up to 7 days, may send duplicates, and doesn’t guarantee order, so your handler must be idempotent. This guide shows the payloads and the rules, based on Meta’s webhook reference (updated mid-2026).

Step 1: verify your webhook endpoint

When you save a callback URL in your Meta app, Meta sends a GET request with three query parameters: hub.mode=subscribe, hub.verify_token (the string you typed in the dashboard) and hub.challenge. If the token matches, respond with HTTP 200 and the hub.challenge value as the body. Any other response fails verification.

• The endpoint must use HTTPS with a valid certificate; self-signed certificates aren’t supported.
• For extra protection Meta supports mutual TLS; IP allow-listing is possible but Meta’s IPs change.

Step 2: check the signature on every event

Each event POST has a header X-Hub-Signature-256: sha256=<hash>. Compute an HMAC-SHA256 of the raw request body with your app secret and compare it with the part after sha256=, using a constant-time comparison. Reject anything that doesn’t match.

The payload for an incoming message

Every event has the same envelope: object: "whatsapp_business_account", then entry[] (the account ID) and changes[] with field: "messages". Inside value you get:

Button taps arrive as their own types: a template quick reply as button with the payload you set, a reply-button or list choice as interactive with the option’s ID. See WhatsApp buttons and list messages.

Status updates: sent, delivered, read, failed

Each status carries id (your message’s ID), recipient_id, timestamp and, on sent and the first of delivered or read, a `pricing` object: pricing_model: "PMP" (per-message pricing), category (marketing, utility, authentication, service…) and type (regular, free_customer_service, free_entry_point). Meta is deprecating the old billable flag and, from Graph API v24.0, omits the conversation object except for free entry point chats.

Retries, duplicates and order

• Retries: any non-200 response, or a timeout, makes Meta retry with decreasing frequency for up to 7 days; after that the event is dropped, and there’s no API to fetch missed webhooks.
• Duplicates: retries can deliver the same event twice. Store message IDs and status changes and ignore repeats.
• Order: messages aren’t guaranteed to arrive in the order you sent them; if order matters, wait for delivered before sending the next.
• Batching: one POST can hold up to 1,000 updates, but don’t rely on it; payloads are up to 3 MB.
• Speed: acknowledge first, then put the event on a queue. Slow handlers cause retries and duplicates.

Subscribing and routing

Useful non-message fields: message_template_status_update (approved, rejected, paused), message_template_quality_update, phone_number_quality_update, account_update, and user_preferences (marketing opt-outs).

Webhooks with Automate AI

If you use Automate AI, Meta’s webhooks come to us: we verify, de-duplicate and store them, update the inbox and campaign reports live, and handle template and quality updates. You can still receive events in your own systems through Automate AI’s developer webhooks (for example message received or status changed) and act through the REST API, without hosting the WhatsApp side yourself. New to the Cloud API? Start with the WhatsApp Cloud API setup guide.