Webhooks from Meta

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

Field NameDescription

account_alerts

Notifies you of decisions related to Official Business Account status or a denial of messaging limit increases. Note that these are independent of developer notifications.

account_review_update

A notification is sent to you when a WhatsApp Business Account has been reviewed.

account_update

A notification is sent to you when a change to your WhatsApp Business Account has occurred. This change can include phone number update, a policy violation, a WhatsApp Business Account has been banned and more.

business_capability_update

Notifies you of changes to a business's capabilities. This can include changes to the maximum number of business phone numbers your WhatsApp Business Account can have, or a change to the messaging limit for all of your WhatsApp Business Account's business phone numbers.

message_template_components_update

Notifies you of changes to a template's components, like a change in title or body, or an addition of a button.

message_template_quality_update

A notification is sent to you when a message template's quality rating changes.

message_template_status_update

A notification is sent to you when the message template has been approved or rejected, or if it has been disabled.

messages

A notification is sent to you when your business has received a message from a customer, when you send a message to a customer, when a message is delivered to a customer, and when your message is read by a customer.

phone_number_name_update

A notification is sent to you when the name associated with a phone number has been approved or rejected.

phone_number_quality_update

A notification is sent to you when the business phone number quality status changes. See Monitor Quality Signals for additional information.

security

A notification is sent to you when:

  • you request to disable two-step verification code
  • the two-step verification code is disabled
  • the two-step verification code is updated

    • template_category_update

    A notification is sent to you when a template's category changes, indicating the template's previous and new category.

    Visit the WhatsApp Business Account Webhooks Reference for more information about each payload field and the WhatsApp Cloud API Webhooks Reference for more information on the different types of messages notifications you can receive.

    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/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

    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/<AP_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

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