Webhook overrides

Updated: Sep 28, 2026

Copy for LLM

Meta sends webhooks to the callback URL set on your app, but you can override the default callback URL by designating an alternate callback URL for the Messaging account 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 Messaging account associated with the number has an alternate callback URL. If the Messaging account has an alternate callback URL, the system sends the webhook there. If the Messaging account 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.

messages
message_echoes
calls
consumer_profile
messaging_handovers
standby
group_lifecycle_update
group_participants_update
group_settings_update
group_status_update
smb_message_echoes
smb_app_state_sync
history
account_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 Messaging account and verify that your alternate callback endpoint can receive and process webhooks correctly.

Set Messaging account alternate callback

Use the Subscribed Apps API to set an alternate callback URL on a Messaging account.

Request syntax

POST /<WABA_ID>/subscribed_apps

Post 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 Meta sends supported webhooks. 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/v26.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 Messaging account alternate callback

Use the Subscribed Apps API to get a list of all apps subscribed to webhooks on the Messaging account. 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 Messaging account alternate callback

Use the Subscribed Apps API to subscribe your app to webhooks on the Messaging account as you normally would (that is, without any post body parameters). Subscribing without post body parameters removes the alternate callback URL from the Messaging account, and Meta sends the Messaging account webhooks to the callback URL set in the App Dashboard again.

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 Meta sends supported webhooks. 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/v26.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_configuration

Response

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 Messaging account associated with the business phone number also has an alternate callback URL set.

Example request

curl 'https://graph.facebook.com/v26.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": ""
  }
}