Webhooks for WhatsApp Business Accounts

You can get real-time notifications when there are changes to your WhatsApp Business Account (WABA) by subscribing at the WhatsApp business account level.

To set up Webhooks for WhatsApp business accounts:

1. Set up your endpoint and configure the Webhooks - These are the same steps that you use to set up Webhooks for Facebook Pages.
2. Subscribe your app under your WhatsApp business account - You must subscribe an app owned by your business —apps shared with your business cannot receive webhook notifications.
3. If you are working as a Solution Partner, make sure to include the whatsapp_business_management permission in your App Review submission.

Set up your endpoint and webhooks

Follow our Webhooks Getting Started guide to create your endpoint and configure your webhook endpoint. When you configure your endpoint, make sure to choose WhatsApp Business Account and subscribe to individual WhatsApp Business Account (WABA) fields.

Available Subscription Fields

Subscribe your app

You need to subscribe your app to webhooks on a given WABA. We only send notifications if your webhooks-configured app is subscribed to webhooks on a given WABA, and only if the app has permission to edit that WABA.

Create a subscription

Request

To subscribe your app to webhooks on a WABA, send a POST request to the WABA > Subscribed Apps endpoint.

curl -X POST 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

Response

Upon success:

{
  "success": "true"
}

Get subscribed apps

To get a list of apps subscribed to webhooks on a WABA, send a GET request to the WABA > Subscribed Apps endpoint.

Request

curl 'https://graph.facebook.com/v24.0/395394933592466/subscribed_apps' \
-H 'Authorization: Bearer BEAiil...'

Response

A successful response will list the subscribed apps:

{
  "data": [
    {
      "whatsapp_business_api_data": {
        "link": "<APP_1_URL>",
        "name": "<APP_1_NAME>",
        "id": "<APP_1_ID>"
      }
    },
    {
      "whatsapp_business_api_data": {
        "link": "<APP_2_URL>",
        "name": "<APP_2_NAME>",
        "id": "<APP_2_ID>"
      }
    },
    ...
  ]
}

Delete a subscription

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

Request

curl -X DELETE 'https://graph.facebook.com/v24.0/395394933592466/subscribed_apps' \
-H 'Authorization: Bearer BEAiil...'

Response

A successful response will read:

{
  "success": "true"
}

Subscribe with Graph API Explorer

If you don't want to subscribe your app with direct API calls, you can easily do it with Graph API Explorer.

Replace the me?fields=id,name query with <WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps. It will subscribe the app you use to send the POST request in Graph Explorer.

Example Webhook payload:

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

Enabling mTLS on a WhatsApp Business Account

You can enable Mutual TLS (mTLS) on the webhooks you receive from WhatsApp for added security.

You must verify the callback URL before enabling mTLS. If you have more than one application accessing WhatsApp Cloud API, you will need to enable mTLS for each application.

mTLS toggle for WhatsApp Business accounts