01 · Definition
What is a webhook field?
A webhook field is a named category of events on the WhatsApp Business Account object, and the full set of webhook fields is the menu your app picks from. Your app subscribes to the fields it wants, and every notification names the field that fired in entry[].changes[].field, with the details in value. messages is by far the busiest: it carries inbound customer messages, the delivery statuses of messages you sent and value-level errors. The other fields report everything around messaging — templates, the account, phone numbers and users.
Meta's catalogue groups naturally. Templates: message_template_status_update (approved, rejected, paused, disabled), message_template_quality_update, message_template_components_update and template_category_update. Account and numbers: account_update (verification, policy violations, restrictions and similar WABA-level changes), account_alerts, account_review_update, business_capability_update (the portfolio's messaging limit, max_daily_conversations_per_business), phone_number_quality_update (a number's throughput level, including THROUGHPUT_UPGRADE), phone_number_name_update (display name review) and security. Users and commerce: user_preferences (marketing stop and resume), automatic_events (purchases and leads detected in Click-to-WhatsApp chats, if you opted in), payment_configuration_update and, for partners, partner_solutions. Coexistence numbers add smb_message_echoes, smb_app_state_sync and history, and calling and groups bring fields of their own (calls, group_lifecycle_update and the other group fields). Not every change gets a field: a user's new business-scoped user ID arrives as a system message on messages, and there is no user_id_update field to subscribe to.
Fields also differ in access and routing. messages needs the whatsapp_business_messaging permission; the others need whatsapp_business_management. Some webhooks are not sent while an app is in development mode. And webhook overrides apply only to some fields, such as messages: template and account fields always go to the app's default callback URL.
This page is about which kinds of event exist and what each delivers. The webhook payload page covers the shared envelope — object, entry, changes, value — that every field arrives in.
Key takeaways
- A webhook field is a named category of WhatsApp Business Account events that your app chooses to receive.
- messages carries inbound messages, delivery statuses and value-level errors; every other field reports templates, the account, numbers or users.
- messages needs the whatsapp_business_messaging permission; every other field needs whatsapp_business_management.
- Fields are chosen per app, but nothing flows until each WABA is attached with POST /{WABA_ID}/subscribed_apps.
- Template and account fields cannot be overridden: they always go to the app's default callback URL.
02 · Specifications
A webhook field: key facts and limits
| Where the field is named | entry[].changes[].field |
|---|---|
| Busiest field | messages (inbound, statuses, errors) |
| Permission for messages | whatsapp_business_messaging |
| Permission for other fields | whatsapp_business_management |
| Template paused | message_template_status_update |
| Portfolio messaging limit | business_capability_update |
| Pricing volume-tier change | account_update (since 1 Oct 2025) |
| Never overridable | Template and account fields |
03 · Code samples
A webhook field in code
const handlers = {messages: onMessagesChange, // inbound, statuses, value-level errorsmessage_template_status_update: onTemplateStatus,template_category_update: onTemplateCategory,account_update: onAccountUpdate,business_capability_update: onCapabilityUpdate,phone_number_quality_update: onNumberQuality,user_preferences: onUserPreferences,};export async function dispatch(payload) {if (payload.object !== "whatsapp_business_account") return;for (const entry of payload.entry ?? []) {for (const change of entry.changes ?? []) {const handler = handlers[change.field];if (!handler) {metrics.increment("whatsapp.webhook.unhandled", { field: change.field });continue; // still acknowledged with 200 upstream}await handler(change.value, { wabaId: entry.id });}}}
One handler per field, and a counter for fields you receive but do not handle yet.
04Playground
A working model of Webhook Fields. Use its controls to replay it step by step.
Route each field to the code that owns it
Only agents with the required skill are eligible; the least busy of them wins.
Incoming · 0 left
- All 10 conversations have been routed.
Conversation 10 of 10 · Skills-based
Display name approved(needs phone_number_name_update)goes toWaiting queue
Skills: nobody covers phone_number_name_update, so it waits for a supervisor instead of going to the wrong agent.
Inbox handler
3 of 4 open
- messages
- Inbound textneeds messages
- Delivered statusneeds messages
- Read statusneeds messages
- Full
Template ops
3 of 3 open
- message_template_status_update
- template_category_update
- Template approvedneeds message_template_status_update
- Template pausedneeds message_template_status_update
- Category changedneeds template_category_update
Account monitor
2 of 3 open
- business_capability_update
- phone_number_quality_update
- account_update
- Limit raisedneeds business_capability_update
- Throughput upgradeneeds phone_number_quality_update
Consent sync
1 of 2 open
- user_preferences
- Marketing stopneeds user_preferences
Waiting · 1
- Display name approvedneeds phone_number_name_update
| Strategy | Routed | Waiting | Skill mismatches |
|---|---|---|---|
| Skills-based | 9 | 1 | 0 |
| Least busy | 10 | 0 | 5 |
Conversation 10 of 10, Display name approved: Skills: nobody covers phone_number_name_update, so it waits for a supervisor instead of going to the wrong agent.
05 · Operation
How does a webhook field work?
Choose fields by job
Start with
messages, then add the fields whose changes you would act on: template status and category for campaign tools,account_update,business_capability_updateandphone_number_quality_updatefor operations,user_preferencesfor consent.Subscribe the app
Create the webhook subscription — callback URL, verify token and fields — in your app's WhatsApp webhook settings, or with
POST /{APP_ID}/subscriptions. This chooses fields but delivers nothing on its own.Attach each WABA
Call the subscribed apps endpoint,
POST /{WABA_ID}/subscribed_apps, for every WhatsApp Business Account whose events the app should receive — the step most often missed when onboarding a new customer.Dispatch on the field first
Route each change by
changes[].fieldto its handler — the messages webhook to the inbox, the template status webhook to campaign tooling, the account update webhook and phone number quality webhook to operations — then inspectvalue. Guessing the event type from the shape ofvaluebreaks as Meta adds fields.Answer 200 for every field
Acknowledge fields you do not handle yet, count them, and decide later. A non-200 for an unknown field makes Meta retry it for days.
06 · Rationale
Why does a webhook field matter?
The fields you subscribe to decide what your systems can notice. Subscribe only to messages and you will learn that a template was paused when a campaign starts failing, that your messaging limit moved when a broadcast is throttled, and that a customer stopped your marketing when a send returns an error. Subscribing to the right handful, and routing each to the code that owns it, turns those surprises into automatic actions — swap the template, pace the campaign, update the suppression list.
07 · Cautions
Common mistakes with a webhook field
Subscribing to messages only
You stay blind to template pauses, recategorisations, limit changes and marketing opt-outs until something fails. Add the operational fields you would act on.
Forgetting subscribed_apps
App-level fields deliver nothing until each WABA is attached with POST /{WABA_ID}/subscribed_apps. New customer, no webhooks? Check this first.
Guessing the event from value
Several fields share similar keys. Dispatch on changes[].field and treat value as that field's schema.
Rejecting fields you do not know
Returning 400 for an unfamiliar field triggers seven days of retries. Acknowledge, count and add a handler when you need it.
08 · Questions and answers
Webhook Fields FAQs
- Which WhatsApp webhook field carries delivery statuses?
- The messages field carries them. Inbound messages and the sent, delivered, read and failed statuses of your outbound messages both arrive on it, distinguished by messages[] or statuses[] inside value.
- Why am I not receiving template status webhooks?
- Usually a missing subscription step. Check that message_template_status_update is subscribed at app level, that the WABA is attached through subscribed_apps, that the app has whatsapp_business_management and is in Live mode; template webhooks always go to the app's default URL, never to an override.
- Do I need a separate callback URL for each webhook field?
- No. One callback URL receives every field you subscribe to, and each change names its field in changes[].field so your code can route it. Overrides can redirect some fields, such as messages, per WABA or phone number.
- Is a STOP reply a user_preferences event?
- No. A typed STOP is an ordinary inbound message on messages. user_preferences reports a marketing stop or resume made through WhatsApp's own controls.
09 · Recommended practice
Best practices for a webhook field
- Review your field list whenever you adopt a new feature — calling, groups and coexistence each bring their own fields.
- Send template and account fields to the team that owns them, not to the support inbox.
- Keep one sample payload per subscribed field in your test suite.
10 · Worked example: A Pune lender's automatic campaign brake
Example: A Pune lender's automatic campaign brake
A Pune consumer-lending company subscribes to messages, message_template_status_update, template_category_update, business_capability_update and user_preferences. When its EMI-reminder template is paused for low quality, the status webhook reaches the campaign service, which stops the send and switches to an approved backup template within a minute. When Meta recategorises a template, the category webhook alerts the team before the next invoice shows a different rate. And when a customer stops marketing messages, the user preferences webhook reaches the consent handler, which suppresses them before the evening offer goes out.