What Webhooks Do
Webhooks are HTTP requests with JSON payloads that Meta sends to your server in response to events on the WhatsApp Business Platform — incoming messages, message status updates, template approvals, account alerts, calling events, settings changes, and more.
Each webhook arrives on a specific subscription field. You subscribe your app to the fields you care about; Meta sends the relevant events to your configured callback URL.
For the inbound message envelope and inbound webhook POST validation model, see Messaging Webhook. For the management events Dualhook ingests and forwards, see Webhook Events & Notifications. For routing message-path events directly to your endpoint, see Webhook Override.
Where They Go in Dualhook
Dualhook's Meta app subscribes to 15 webhook fields. Each field reaches you one of three ways:
| Field | Dualhook subscribed? | Routing |
|---|---|---|
messages, smb_message_echoes, history, smb_app_state_sync | Yes | Direct to your endpoint via Webhook Override. Dualhook does not ingest these. |
Management fields: account_update, account_review_update, account_alerts, business_capability_update, message_template_status_update, message_template_quality_update, message_template_components_update, template_category_update, phone_number_quality_update, phone_number_name_update, security | Yes | App callback → Dualhook → forwarded to your endpoint with X-Dualhook-* headers. Partner lifecycle events inside account_update are consumed by Dualhook and not forwarded. |
Everything else: user_preferences, calls, account_settings_update, message_echoes, consumer_profile, messaging_handovers, standby, the group_* fields, partner_solutions, payment_configuration_update, automatic_events | No | Not delivered by a Dualhook connection. To receive them, subscribe your own Meta app to the field and to the WABA. |
Dualhook ingests the forwarded management events for state tracking (so the dashboard stays in sync with Meta) and forwards them to you. A customer cannot change which fields Dualhook's app subscribes to.
For Coexistence onboarding, Dualhook triggers Meta's one-time history and smb_app_state_sync sync requests after Webhook Override is accepted. Meta delivers any resulting payloads directly to your endpoint; the trigger acceptance is not a delivery guarantee.
Subscribing to Fields
Once your webhook endpoint is configured, subscribe your app to individual fields:
- App Dashboard → WhatsApp → Configuration panel.
- Or, for apps created via the "Connect with customers through WhatsApp" use case: App Dashboard → Use cases → Customize → Configuration.
You can also override the callback URL per WABA or per business phone number — useful when partners want unique endpoints for each onboarded customer. See Webhook Override.
Permissions
| Permission | Required for |
|---|---|
whatsapp_business_messaging | The messages and calls webhook fields |
whatsapp_business_management | All other webhook fields |
If you're a partner needing these permissions to serve business customers, you must be approved for advanced access via App Review before customers can grant the permissions during onboarding. See WhatsApp Business API Permissions.
All Subscription Fields
| Field | What it notifies you of |
|---|---|
messages | Inbound messages from users + outbound message status updates (sent / delivered / read / failed). The "main" field. |
message_template_status_update | Template review outcome — APPROVED / REJECTED / FLAGGED / etc. |
message_template_quality_update | Template quality score changes |
message_template_components_update | Changes to a template's components after the template is edited |
template_category_update | Template category reclassification (e.g. UTILITY → MARKETING) |
phone_number_quality_update | Phone number messaging-limit and throughput changes |
phone_number_name_update | Display name verification outcomes |
account_update | Partner-led business verification, auth-international rate eligibility, primary business location, WABA sharing, policy violations, offboarding, reconnection, deletion. Also carries pricing tier updates and MM API onboarding events. |
account_alerts | Messaging limit changes, business profile changes, OBA status changes |
account_review_update | WABA reviewed against policy guidelines |
business_capability_update | Capability changes (messaging limits, phone number caps, etc.) |
account_settings_update | Phone number settings changed — currently only calling settings |
security | Security setting changes on a phone number |
user_preferences | Marketing-message stop / resume actions by users |
partner_solutions | Multi-Partner Solution status changes |
payment_configuration_update | Payment config changes for Payments API India and Brazil |
messaging_handovers | Thread ownership changes (control_passed, control_taken) under Conversation Routing |
standby | Inbound messages, echoes, and statuses on threads another responder owns under Conversation Routing |
automatic_events | Detected purchase / lead events on Click-to-WhatsApp ad chats (opt-in feature) |
calls | All calling events — call connect, status, terminate. Required for Calling API users not on SIP. SIP numbers get only call created and terminate, and only with webhook_delivery enabled. |
history | One-time chat history sync for WhatsApp Business app users onboarded via Coexistence. Dualhook requests the sync after onboarding; Meta routes the payload directly to your endpoint if the business shared history. |
smb_app_state_sync | Contact sync for WhatsApp Business app users onboarded via Coexistence. Dualhook requests the initial sync after onboarding; Meta routes this directly to your endpoint via Webhook Override. |
smb_message_echoes | Echoes of messages sent via the WhatsApp Business app or a linked device by an onboarded SMB customer. |
Meta's references now call entry[].id the Messaging account ID. It is the same value as the WABA ID that Dualhook shows for the connection.
The messages field carries many sub-types (text / image / interactive / button reply / call_permission_reply / etc.) — your handler should switch on messages[].type and messages[].interactive.type to route them.
Override Webhooks
Use a different webhook callback URL for specific subscription fields on a WABA or phone number — see Webhook Override. Useful for testing or for partners that want per-customer endpoints.
In Dualhook setups, override is how message-path and supported Coexistence fields bypass Dualhook and go straight to your endpoint.
Payload Size
Webhook payloads can be up to 3 MB. Larger payloads are rejected at the source — Meta won't send them.
Delivery Retries
If your endpoint returns a non-200 status code, or if delivery fails for another reason, Meta retries with decreasing frequency for up to 7 days.
Retries are sent to all apps subscribed to the field on the WABA — so if you have multiple apps on the same WABA, each gets its own retry cycle, which can produce duplicate notifications for already-handled events. Idempotency at your endpoint is mandatory.
For calling-related webhooks, the retry policy is shorter (Meta hasn't published exact numbers) — check the timestamp field and skip stale events.
IP Allowlisting
If you must allowlist by IP, get the current Meta address space:
whois -h whois.radb.net -- '-i origin AS32934' | grep '^route' | awk '{print $2}' | sort
Or download the geofeed CSV from Meta's webhook docs. As of mid-2024 this collapses to ~23 IPv4 prefixes. Meta changes IPs periodically, so set up monitoring to refresh your allowlist.
Troubleshooting
If you're not receiving webhooks:
- Confirm your endpoint accepts requests and returns 200.
- Send a test payload from App Dashboard → WhatsApp → Configuration to verify reachability.
- Confirm the field is subscribed and your app has the right permission (
messagesandcallsneedwhatsapp_business_messaging; everything else needswhatsapp_business_management). On a Dualhook connection, check the routing table first: fields Dualhook does not subscribe to never arrive. If you use your own Meta app, it must be in Live mode; Meta does not send some webhooks to apps in Development mode. - Check whether an IP allowlist, firewall, proxy, or other transport-level rule is rejecting Meta's request.
- Use the connection's Health page in Dualhook to inspect Meta's view of your subscribed_apps + webhook config.
For Webhook Override / inbound webhook POST validation specifics, see Messaging Webhook.