Appearance
Webhook overrides
Updated: Jun 28, 2026
Meta sends webhooks to the callback URL set on your app, but you can override this by designating an alternate callback URL for the WhatsApp Business account (WABA) or business phone number.
When a supported field triggers a webhook, the system first checks if your app has designated an alternate callback URL for the business phone number associated with the event. If the business phone number has an alternate callback URL, the system sends the webhook there. If the phone number has no alternate, the system checks if the WABA associated with the number has an alternate callback URL. If the WABA has an alternate callback URL, the system sends the webhook there. If the WABA also has no alternate, the webhook falls back to your app's callback URL.
Supported webhook fields
The override applies only to the following webhook field types. For field types not listed here, Meta always sends webhooks to your app's default callback URL.
messagesmessage_echoescallsconsumer_profilemessaging_handoversgroup_lifecycle_updategroup_participants_updategroup_settings_updategroup_status_updatesmb_message_echoessmb_app_state_synchistoryaccount_settings_update
Note: Template webhooks (
message_template_status_update,message_template_quality_update,message_template_components_update,template_category_update) and account-level webhooks (account_update,account_review_update,account_alerts) do not support callback overrides. Meta always delivers these webhooks to your app's default callback URL.
Requirements
Before setting an alternate callback URL, make sure your app is subscribed to webhooks on the WABA and verify that your alternate callback endpoint can receive and process webhooks correctly.
Set WABA alternate callback
Use the Subscribed Apps API to set an alternate callback URL on a WABA.
Request syntax
POST /<WABA_ID>/subscribed_appsPost body
{
"override_callback_uri":"<WABA_ALT_CALLBACK_URL>",
"verify_token":"<WABA_ALT_CALLBACK_URL_TOKEN>"
}Body parameters
| Placeholder | Description | Example value |
|---|---|---|
<WABA_ALT_CALLBACK_URL> | Required. Alternate callback URL where supported webhooks should be sent. Maximum 200 characters. | https://my-waba-alternate-callback.com/webhook |
<WABA_ALT_CALLBACK_URL_TOKEN> | Required. Alternate callback URL verification token. No maximum length. | myvoiceismypassport? |
Response
Upon success:
{
"success": true
}Example request
curl -X POST \
'https://graph.facebook.com/v25.0/102290129340398/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...' \
-H 'Content-Type: application/json' \
-d '
{
"override_callback_uri":"https://my-waba-alternate-callback.com/webhook",
"verify_token":"myvoiceismypassport?"
}'Example response
{
"success": true
}Get WABA alternate callback
Use the Subscribed Apps API to get a list of all apps subscribed to webhooks on the WABA. The response should include an override_callback_uri property and value.
Example response
{
"data" : [
{
"whatsapp_business_api_data" : {
"id" : "670843887433847",
"link" : "https://www.facebook.com/games/?app_id=67084...",
"name" : "Lucky Shrub"
},
"override_callback_uri" : "https://my-waba-alternate-callback.com/webhook"
}
]
}Delete WABA alternate callback
Use the Subscribed Apps API to subscribe your app to webhooks on the WABA as you normally would (that is, without any post body parameters). Subscribing without post body parameters removes the alternate callback URL from the WABA, and webhooks for the WABA will once again be sent to the callback URL set in the App Dashboard.
Set phone number alternate callback
Use the WhatsApp Business Phone Number API to set an alternate callback URL on the business phone number.
Request syntax
POST /<BUSINESS_PHONE_NUMBER_ID>Post body
{
"webhook_configuration": {
"override_callback_uri": "<PHONE_ALT_CALLBACK_URL>",
"verify_token": "<PHONE_ALT_CALLBACK_URL_TOKEN>"
}
}Body parameters
| Placeholder | Description | Example value |
|---|---|---|
<PHONE_ALT_CALLBACK_URL> | Required. Alternate callback URL where supported webhooks should be sent. Maximum 200 characters. | https://my-phone-alternate-callback.com/webhook |
<PHONE_ALT_CALLBACK_URL_TOKEN> | Required. Alternate callback URL verification token. No maximum length. | myvoiceismypassport? |
Response
Upon success:
{
"success": true
}Example request
curl -X POST 'https://graph.facebook.com/v25.0/106540352242922' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"webhook_configuration": {
"override_callback_uri": "https://my-phone-alternate-callback.com/webhook",
"verify_token": "myvoiceismypassport?"
}
}'Example response
{
"success": true
}Get phone number alternate callback
Use the WhatsApp Business Phone Number API and request the webhook_configuration field to verify that the business phone number has an alternate callback URL.
Request syntax
GET /<BUSINESS_PHONE_NUMBER_ID>
?fields=webhook_configurationResponse
Upon success:
{
"webhook_configuration": {
"phone_number": "<PHONE_ALT_CALLBACK_URL>",
"whatsapp_business_account": "<WABA_ALT_CALLBACK_URL>",
"application": "<APP_CALLBACK_URL>"
},
"id": "106540352242922"
}The whatsapp_business_account property is only included if the WABA associated with the business phone number also has an alternate callback URL set.
Example request
curl 'https://graph.facebook.com/v25.0/106540352242922?fields=webhook_configuration' \
-H 'Authorization: Bearer EAAJB...'Example response
{
"webhook_configuration": {
"phone_number": "https://my-phone-alternate-callback.com/webhook",
"whatsapp_business_account": "https://my-waba-alternate-callback.com/webhook",
"application": "https://my-production-callback.com/webhook"
},
"id": "106540352242922"
}Delete phone number alternate callback
To delete a business phone number's alternate callback URL, use the WhatsApp Business Phone Number API with the override_callback_uri property set to an empty string:
{
"webhook_configuration": {
"override_callback_uri": ""
}
}