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.
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.
Key facts
{raw body} The POST body exactly as sent, with no timestamp or other data added.
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.
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
not published Meta's standard is a 250ms median, with under 1% above 1s Retries up to 7 days decreasing frequency; only a 200 counts as success After retries dropped no API fetches past webhooks, so keep your own copy Ordering not documented Meta delivers concurrently, so don't rely on arrival order Known failure modes
From Hookdeck's WhatsApp guide →-
No webhooks ever arrive
Meta sends nothing until your endpoint answers a GET with a
Testing your endpoint →200and thehub.challengevalue, 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. -
Deduplicating on the message id drops statuses
A status webhook's
Handle duplicates →idis the id of your message, so sent, delivered and read all share it. Deduplicate statuses onidandstatustogether. -
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
Handle ordering →deliveredwebhook. Treatreadas proof of delivery, and only move a message's status forward. -
An outage longer than 7 days loses events
Meta retries anything other than a
Retries and lost events →200for 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.
WhatsApp webhook best practices
- Verify every signature. 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. Meta treats any other status as a failure, including other 2xx codes, and retries the delivery.
- Respond fast and process in the background. Meta asks for a median latency of 250ms with under 1% above 1s, under concurrent requests.
- Deduplicate statuses on id and status together. Sent, delivered and read webhooks all carry the same message id, so the id alone drops real updates.
- Store every payload before processing it. No API fetches past webhooks, and Meta drops anything still undelivered after 7 days.
- Size your servers for 3x your outgoing traffic. Meta's guidance is 3x outgoing message traffic plus 1x incoming, because each message can send three statuses.
Common WhatsApp webhook events
Messages
messages | User sends a message, or a message you sent changes status |
calls | Call connects, changes status or ends |
user_preferences | User stops or resumes marketing messages |
Templates
message_template_status_update | Template is approved, rejected, disabled, archived or unarchived |
message_template_quality_update | Template's quality score changes |
template_category_update | Template's category changes, or is about to change |
Account and phone numbers
account_update | Verification, sharing, policy or deletion change on a Messaging account |
account_alerts | Alert on messaging limits, profile photo or Official Business Account status |
phone_number_quality_update | Business phone number's throughput level changes |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
messaging | 8 | 4 |
account | 5 | 4 |
group | 4 | 4 |
template | 4 | 4 |
business_app | 3 | 3 |
phone_number | 3 | 3 |
1 more resource, including Other WhatsApp events. All 29 events →
In this hub
| Webhook events → | Every covered WhatsApp event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to WhatsApp events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill whatsapp-webhooks |
Keep a long outage from losing your WhatsApp messages.
Hookdeck Event Gateway accepts each WhatsApp delivery, queues it and retries to your service on your schedule, and keeps a log of every attempt so you can replay what failed.