# WhatsApp webhooks

WhatsApp webhooks are signed JSON POSTs that Meta sends to your server about incoming messages, the status of messages you sent, calls, templates and changes to your account.

Agent skill: `npx skills add hookdeck/webhook-skills --skill whatsapp-webhooks` ([details](https://hookdeck.com/webhooks/whatsapp/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [WhatsApp's official docs](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks).

[Overview](https://hookdeck.com/webhooks/whatsapp) · [Webhook events (29)](https://hookdeck.com/webhooks/whatsapp/events) · [MCP events](https://hookdeck.com/webhooks/whatsapp/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/whatsapp/verify) · [Production guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/whatsapp/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Hub-Signature-256` Format: sha256=<hex> | [WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint) |
| Scheme | `HMAC-SHA256` | [WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint) |
| Signed material | `{raw body}` The POST body exactly as sent, with no timestamp or other data added. | [WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint) |
| How events are identified | `entry[].changes[].field field in the body` | [WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview) |
| Body format | `JSON` Content type: application/json. | [WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint) |
| URL handshake | `GET: echo the challenge` HTTP 200 with the hub.challenge value, after comparing hub.verify_token with the string stored on your server. Anything else leaves the endpoint unverified and no webhooks are sent. | [WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint) |
| Envelope | `object, entry` | [WhatsApp docs](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill whatsapp-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/whatsapp/skill) |

[Verify WhatsApp webhooks](https://hookdeck.com/webhooks/whatsapp/verify)

## How WhatsApp webhooks work

The WhatsApp Business Platform relies on webhooks because there's nothing to poll: the contents of a message from a user only reach you by webhook, all delivery status updates arrive the same way, and no API fetches past webhooks. You set one callback URL on your Meta app, pass a GET handshake, then subscribe to the fields you want. Meta sends each update as a POST signed with `X-Hub-Signature-256`.

Every payload has `object` set to `whatsapp_business_account` and an `entry` array, and `entry[].changes[].field` names the subscription, such as `messages`. The update itself is in `value`. The `messages` field covers two things: `value.messages[]` holds what users send you and `value.statuses[]` reports on what you sent. A POST can batch up to 1000 updates, so read every item. There is no version header or field, though Meta describes some payload changes by Graph API version.

## Setting up WhatsApp webhooks

- In the App Dashboard, open WhatsApp, then Configuration, and add your Callback URL and Verify token. Apps made with the Connect with customers through WhatsApp use case have this under Use cases, Customize, Configuration. Meta verifies the URL with a GET straight away, and the list of fields appears once that passes.
- Subscribe to the fields you need, then check your app is subscribed to the Messaging account with `GET /<WABA_ID>/subscribed_apps`. Subscribe it with a POST to the same path if it isn't. Solution providers must do this for every customer's account.
- Test from the same panel, which can send a test payload to your endpoint, or tunnel to localhost with the Hookdeck CLI. Meta needs a public HTTPS URL with a valid certificate, and self-signed certificates aren't supported. Some webhooks are only sent when your app is in Live mode.
- You can't resend a webhook from Meta's side, and no API returns past webhooks, so store every payload you receive.

## Delivery behaviour

- **Timeout:** not published. Meta's standard is a 250ms median, with under 1% above 1s. [Guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 7 days. decreasing frequency; only a 200 counts as success. [Guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** dropped. no API fetches past webhooks, so keep your own copy. [Guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not documented. Meta delivers concurrently, so don't rely on arrival order. [Guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **No webhooks ever arrive.** Meta sends nothing until your endpoint answers a GET with a `200` and the `hub.challenge` value, so a POST-only route never receives an event. If the handshake passed, check you've subscribed to the field, your app is subscribed to the Messaging account, and it's in Live mode. [Testing your endpoint](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#testing)
2. **Deduplicating on the message id drops statuses.** A status webhook's `id` is the id of your message, so sent, delivered and read all share it. Deduplicate statuses on `id` and `status` together. [Handle duplicates](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#duplicates)
3. **A read status can arrive with no delivered status.** When a user has the chat open, a message is delivered and read at once, and Meta skips the `delivered` webhook. Treat `read` as proof of delivery, and only move a message's status forward. [Handle ordering](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#ordering)
4. **An outage longer than 7 days loses events.** Meta retries anything other than a `200` for up to 7 days, then drops the webhook, and no API fetches it again. Message contents only reach you this way, so store every payload as it arrives. [Retries and lost events](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#retries)

From [Hookdeck's WhatsApp guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts).

## WhatsApp webhook best practices

- **[Verify every signature](https://hookdeck.com/webhooks/whatsapp/verify).** Compute the HMAC over the raw body with your app secret, so a forged POST can't reach your handler.
- **[Return a 200 and nothing else](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#timeouts).** Meta treats any other status as a failure, including other 2xx codes, and retries the delivery.
- **[Respond fast and process in the background](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#timeouts).** Meta asks for a median latency of 250ms with under 1% above 1s, under concurrent requests.
- **[Deduplicate statuses on id and status together](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#duplicates).** Sent, delivered and read webhooks all carry the same message id, so the id alone drops real updates.
- **[Store every payload before processing it](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#retries).** No API fetches past webhooks, and Meta drops anything still undelivered after 7 days.
- **[Size your servers for 3x your outgoing traffic](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts#other-limits).** Meta's guidance is 3x outgoing message traffic plus 1x incoming, because each message can send three statuses.

## Common WhatsApp webhook events

### Messages

- [messages](https://hookdeck.com/webhooks/whatsapp/events#messages): User sends a message, or a message you sent changes status
- [calls](https://hookdeck.com/webhooks/whatsapp/events#calls): Call connects, changes status or ends
- [user_preferences](https://hookdeck.com/webhooks/whatsapp/events#user_preferences): User stops or resumes marketing messages

### Templates

- [message_template_status_update](https://hookdeck.com/webhooks/whatsapp/events#message_template_status_update): Template is approved, rejected, disabled, archived or unarchived
- [message_template_quality_update](https://hookdeck.com/webhooks/whatsapp/events#message_template_quality_update): Template's quality score changes
- [template_category_update](https://hookdeck.com/webhooks/whatsapp/events#template_category_update): Template's category changes, or is about to change

### Account and phone numbers

- [account_update](https://hookdeck.com/webhooks/whatsapp/events#account_update): Verification, sharing, policy or deletion change on a Messaging account
- [account_alerts](https://hookdeck.com/webhooks/whatsapp/events#account_alerts): Alert on messaging limits, profile photo or Official Business Account status
- [phone_number_quality_update](https://hookdeck.com/webhooks/whatsapp/events#phone_number_quality_update): Business phone number's throughput level changes

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [messaging](https://hookdeck.com/webhooks/whatsapp/events#resource-messaging) | 8 | 4 |
| [account](https://hookdeck.com/webhooks/whatsapp/events#resource-account) | 5 | 4 |
| [group](https://hookdeck.com/webhooks/whatsapp/events#resource-group) | 4 | 4 |
| [template](https://hookdeck.com/webhooks/whatsapp/events#resource-template) | 4 | 4 |
| [business_app](https://hookdeck.com/webhooks/whatsapp/events#resource-business-app) | 3 | 3 |
| [phone_number](https://hookdeck.com/webhooks/whatsapp/events#resource-phone-number) | 3 | 3 |

1 more resource. [All 29 events](https://hookdeck.com/webhooks/whatsapp/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/whatsapp/events): Every covered WhatsApp event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/whatsapp/mcp-events): How an agent subscribes to WhatsApp events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/whatsapp/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/whatsapp/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill whatsapp-webhooks`
---

Not affiliated with WhatsApp. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/whatsapp.json) · [Report a correction](https://hookdeck.com/contact)
