Webhook Overrides

Cloud API only.

Messages webhooks are sent to the callback URL set on your app, but you can override this by setting an alternate callback URL on your WhatsApp Business Account (WABA) or business phone number.

When a messages webhook is triggered, we will first check if the business phone number associated with the message has an alternate callback URL. If it does, we will send the webhook to the alternate callback URL. If it has no alternate, we will check if the WABA associated with the phone number has an alternate callback URL and send it there. If the WABA also has no alternate, we will then fallback to the app's callback URL.

Requirements

Before setting an alternate callback URL, make sure your app is subscribed to webhooks for the WABA and verify that your alternate callback endpoint can receive and process messages webhooks correctly.

Set WABA Alternate Callback

Use the POST /<WABA_ID>/subscribed_apps endpoint to set an alternate callback URL on a WABA.

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

Response

Upon success:

{
  "success": true
}

Example Request

curl -X POST \
'https://graph.facebook.com/v19.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 GET /<WABA_ID>/subscribed_apps endpoint 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 POST /<WABA_ID>/subscribed_apps endpoint to subscribe your app to webhooks on the WABA as you normally would (i.e. without any post body parameters). This will remove the alternate endpoint's callback URL from the WABA, and messages 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 POST /<BUSINESS_PHONE_NUMBER_ID> endpoint 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

Response

Upon success:

{
  "success": true
}

Example Request

curl 'https://graph.facebook.com/v19.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 GET /<BUSINESS_PHONE_NUMBER_ID> endpoint 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"
}

Note that whatsapp_business_account 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/v17.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 POST /<BUSINESS_PHONE_NUMBER_ID> endpoint with the override_callback_uri property set to an empty string:

{
  "webhook_configuration": {
    "override_callback_uri": "",
  }
}