Managing Webhooks

WhatsApp Business Accounts (WABAs) and their assets are objects in the Facebook Social Graph. When a trigger event occurs to one of those objects, Facebook sees it and sends a notification to the webhook URL specified in your Facebook App's dashboard.

In the context of embedded signup, you can use webhooks to get notifications of changes to your WABAs, phone numbers, message templates, and messages sent to your phone numbers.

You need to individually subscribe to every WABA for which you wish to receive Webhooks. After fetching the client's WABA ID, subscribe your app to the ID in order to start receiving Webhooks.

See Webhooks for WhatsApp Business Accounts for more information about subscribing to Webhooks.

Subscribe to a WhatsApp Business Account

First, set up the Webhooks product for your app:

1. Load your app in the App Dashboard and add the Webhooks product if you have not already added it.
2. Click the Webhooks product in the menu on the left.
3. Select WhatsApp Business Account from the drop-down menu and then click Subscribe to this object.
4. Add your Webhooks callback URL and verification token, verify, and save your changes.

For more information about subscribing to Webhooks in the App Dashboard, see Configuring the Webhooks Product.

Once you have set up webhooks in the Webooks product panel, send a POST request to the subscribed_apps endpoint on the WhatsApp Business Account you want to receive webhooks for.

Include your system uses access token in the request header, preceded by Authorization: Bearer. For help generating a system user access token, see System Users, Install Apps and Generate Tokens.

Request Syntax

POST https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Sample Request

curl -X POST \
'https://graph.facebook.com/v21.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Sample Response

{
   "success" : true
}

Your app (identified by the system user access token) should now receive webhooks notifications describing changes to the WhatsApp Business Account.

Repeat this process for any other WABA for which you wish you receive webhooks notifications. Note that if you subscribe your app to webhooks for multiple WABAs, all webhooks notifications will be sent to the app's callback URL specified in the Webhooks product panel of the App Dashboard.

If you wish to use different callback URLs for each WABA, you must create separate apps, each with their own callback URL, for each WABA and perform the query above on each WABA using each app's system user access token. Alternatively, if you want to use a single app, you can override the callback URL when subscribing to webhooks for each WABA. See Overriding the Callback URL.

Get All Subscriptions for a WABA

To get a list of apps subscribed to webhooks for a WABA, send a GET request to the subscribed_apps endpoint on the WABA:

Request Syntax

GET https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

A successful response includes an array of apps that have subscribed to the WABA, with link, name, and id properties for each app.

Sample Request

curl \
'https://graph.facebook.com/v21.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Sample Response

{
  "data" : [
    {
      "whatsapp_business_api_data" : {
        "id" : "67084...",
        "link" : "https://www.facebook.com/games/?app_id=67084...",
        "name" : "Jaspers Market"
      }
    },
    {
      "whatsapp_business_api_data" : {
        "id" : "52565...",
        "link" : "https://www.facebook.com/games/?app_id=52565...",
        "name" : "Jaspers Fresh Finds"
      }
    }
  ]
}

Unsubscribe from a WABA

To unsubscribe your app from webhooks for a WhatsApp Business Account, send a DELETE request to the subscribed_apps endpoint on the WABA.

Request Syntax

DELETE https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Sample Request

curl -X DELETE \
'https://graph.facebook.com/v21.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Sample Response

{
   "success" : true
}

Overriding the Callback URL

See Webhooks Overrides.

Set Up Notifications

You can set up webhooks to send you notifications of changes to your subscribed WhatsApp Business Accounts. The types of notifications you can subscribe to are:

Available Subscription Fields

See the Webhooks for WhatsApp Business Accounts documentation for more information.

Webhooks Format

You get notifications in the following general format:

{
  "object": "whatsapp_business_account",
  "entry": [
    { // entry object, containing changes
      "changes": [
        { // changes object, containing value
          "value": {
            // value object
          }
        }
      ]
    }
  ]
}

See more details about each field:

• object
• entry
• changes
• value

Examples

Onboarded business customer

An account_update webhook is triggered with event set to PARTNER_ADDED when a business customer successfully completes the Embedded Signup flow.

Syntax

{
  "entry": [
    {
      "id": "<BUSINESS_PORTFOLIO_ID>",
      "time": <WEBHOOK_SENT_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "<EVENT>",
            "waba_info": {
              "waba_id": "<CUSTOMER_WABA_ID>",
              "owner_business_id": "<CUSTOMER_BUSINESS_PORTFOLIO_ID>"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Example

{
  "entry": [
    {
      "id": "35602282435505",
      "time": 1731617831,
      "changes": [
        {
          "value": {
            "event": "PARTNER_ADDED",
            "waba_info": {
              "waba_id": "495709166956424",
              "owner_business_id": "942647313864044"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Phone Number Updates

Name Update Received

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243053,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "16505551111",
            "decision": "APPROVED",
            "requested_verified_name": "WhatsApp",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

Quality Update Received

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243062,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "16505551111",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

WABA Updates

Sandbox number upgraded to Verified Account

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505551111",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

WhatsApp Business Account Banned

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "January 31, 2021"
            }
          }
        }
      ]
    }
  ]
}

WhatsApp Business Account Review Completed

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

Message Template Updates

Approved

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "APPROVED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "NONE"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}