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.

29 events covered

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

Signature header
X-Hub-Signature-256

Format: sha256=<hex>

Scheme
HMAC-SHA256
Signed material
{raw body}

The POST body exactly as sent, with no timestamp or other data added.

How events are identified
entry[].changes[].field field in the body
Body format
JSON

Content type: application/json.

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.

Envelope
object, entry
Agent skill
npx skills add hookdeck/webhook-skills --skill whatsapp-webhooks

Verify WhatsApp webhooks →

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

  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 →
  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 →
  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 →
  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 →

WhatsApp webhook best practices

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

automatic_events · calls · consumer_profile · message_echoes +4

8 4
account

account_alerts · _review_update · _settings_update · _update +1

5 4
group

group_lifecycle_update · _participants_update · _settings_update · _status_update

4 4
template

message_template_components_update · message_template_quality_update · message_template_status_update · _category_update

4 4
business_app

history · smb_app_state_sync · smb_message_echoes

3 3
phone_number

phone_number_name_update · _quality_update · security

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.

Not affiliated with WhatsApp. Facts are compiled from public sources and linked inline.