Webhooks

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. Make sure your app has completed App Review and requested the whatsapp_business_management permission.

GET, POST, and DELETE calls to /{whats-app-business-account-id}/subscribed_apps are now subject to Business Use Case Rate Limits.

Set up Your Endpoint and Webhooks

Follow our Webhooks Getting Started guide to create your endpoint and configure your Webhooks. When you configure your Webhooks, make sure to choose WhatsApp Business Account and subscribe to one or more WhatsApp business account fields.

Field Name Description

message_template_status_update

Notifies you when the message template status changes, by being approved or rejected, or if it has been disabled.

phone_number_name_update

Notifies you when the name review associated with a phone number has a status update.

phone_number_quality_update

Notifies you when the quality-related status of a phone number has an update.

account_update

Notifies you when a WABA has been upgraded from unverified trial experience to a verified account, or if a WABA has been banned.

account_review_update

Notifies you when a WABA has been reviewed.

Subscribe Your App

You need to subscribe your app to Webhook notifications for the WhatsApp business account. We only send notifications when your Webhooks-configured app is subscribed under the WhatsApp business account, and when the app has permission to edit the WhatsApp business account.

Create a subscription

Request

To subscribe your app, have your app send a POST request to the subscribed_apps endpoint for the WhatsApp business account:

curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<VERSION>/<WHATSAPP_BUSINESS_ACCT_ID>/subscribed_apps"

Response

A successful response will read:

{"success": "true"}

Retrieve a subscription list

To see which apps your WhatsApp business account has subscribed to, send a GET request to the subscribed_apps endpoint.

Request

curl -i -X GET \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<VERSION>/<WHATSAPP_BUSINESS_ACCT_ID>/subscribed_apps"

Response

A successful response will list the subscribed apps:

{
 "data": [
 { 
"name": "<APP_NAME>", 
"id": "<APP_ID>" } ]
}

Delete a subscription

To delete a subscription for an app, send a DELETE request to the subscribed_apps endpoint.

Request

curl -i -X DELETE \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<VERSION>/<WHATSAPP_BUSINESS_ACCT_ID>/subscribed_apps"

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_ACCT_ID>/subscribed_apps. It will subscribe the app you use to send the POST request in Graph Explorer.

Your app must have permission to edit the WhatsApp business account in order to successfully subscribe.

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
            }
          }
        ]
      }
    ]
  }
]