What Webhook Override Is
Webhook Override is Meta's alternate-callback routing for WhatsApp webhook fields. Instead of sending supported webhook fields to the default callback URL on the Meta app, Meta can send them directly to an alternate callback URL configured for a WhatsApp Business Account (WABA) or for a specific business phone number.
Dualhook uses this so customer message-path traffic goes from Meta to your endpoint directly. Dualhook is not a message proxy in that flow.
In a healthy Dualhook connection with override active:
- Meta sends supported customer-path fields to your configured endpoint.
- Dualhook does not receive, inspect, store, forward, or replay those payloads.
- Dualhook still receives non-overridable management fields on its app-level callback so it can maintain dashboard state, account alerts, and operational metadata.
This is the core privacy boundary: message content, media metadata, chat history, app echoes, and contact-sync payloads do not pass through Dualhook when override is active.
Routing Priority
For a supported webhook field, Meta resolves the destination in this order:
- Phone-number-level alternate callback, if configured.
- WABA-level alternate callback, if configured.
- The default app callback URL, if no alternate callback exists.
Dualhook's standard completed setup uses the WABA-level override path. A phone-number-level override, if configured outside Dualhook, takes precedence for that phone number.
For webhook fields that do not support override, Meta always sends the webhook to the default app callback URL.
Fields That Can Be Overridden
Meta's override support applies only to specific webhook field types:
| Field | Typical path in Dualhook |
|---|---|
messages | Your endpoint |
message_echoes | Your endpoint |
calls | Your endpoint when calling webhooks are used |
consumer_profile | Your endpoint if subscribed |
messaging_handovers | Your endpoint if subscribed |
group_lifecycle_update | Your endpoint if subscribed |
group_participants_update | Your endpoint if subscribed |
group_settings_update | Your endpoint if subscribed |
group_status_update | Your endpoint if subscribed |
smb_message_echoes | Your endpoint |
smb_app_state_sync | Your endpoint |
history | Your endpoint |
account_settings_update | Your endpoint if subscribed |
The important operational point is that supported fields are not forwarded by Dualhook. Meta chooses the callback target and sends the webhook there directly.
What Stays on Dualhook
Fields that do not support override stay on the app-level callback. Dualhook handles these as operational metadata, not message content.
Examples include:
message_template_status_updatemessage_template_quality_updatemessage_template_components_updatetemplate_category_updateaccount_updateaccount_review_updateaccount_alertsbusiness_capability_updatesecurity
Dualhook may forward normalized management notifications to your configured endpoint and logs delivery metadata for those operational events. It does not store customer message bodies or media.
What Dualhook Configures
During onboarding, Dualhook collects your webhook endpoint URL and verify token before the Meta Embedded Signup popup opens. After signup completes, Dualhook subscribes the WABA and asks Meta to use your endpoint as the alternate callback for supported fields.
The verify token is used by Meta's GET challenge when it verifies your endpoint. Dualhook stores it only for configuration and retry purposes.
Dualhook's standard connection path uses WABA-level override. That means all phone numbers under the same connected WABA share the same webhook URL and verify token in Dualhook. Per-phone-number override is a Meta capability, and Dualhook surfaces phone-level routing in diagnostics when Meta reports it.
Coexistence Syncs
For Coexistence connections, Dualhook triggers Meta's one-time history and smb_app_state_sync sync requests after override is accepted.
Those trigger calls are not the payload delivery path. If the business approved history or contact sharing, Meta sends the resulting history and smb_app_state_sync webhooks directly to your endpoint through the active override.
A successful trigger only means Meta accepted the request. It does not prove that the business shared history, that Meta generated every chunk, or that your endpoint received and parsed every webhook.
Debugging Routing
The connection Debug tab in Dualhook checks the routing signals Meta exposes:
- phone-number webhook configuration,
- WABA-level webhook override from subscribed apps,
- app-level callback context.
If override is active, supported fields should be delivered to your endpoint and should not appear in Dualhook's management-event logs.
If override is not active yet, supported fields can fall back to Dualhook's app-level callback. Dualhook's app callback defensively acknowledges those fallback payloads without processing or storing them. That state usually means setup is incomplete, the endpoint failed verification, billing paused the connection, or a routing change is still being applied.
For the event categories Dualhook does handle, see Webhook Events & Notifications.