WhatsApp Business Platform

Managing webhooks

Updated: Jun 30, 2026
Copy for LLM
Embedded Signup v2 and v3 will be deprecated on October 15, 2026, including their public preview versions. Migrate your integration to v4 before that date to avoid disruption. See Versions for the full upgrade path.
Messaging accounts and their assets are objects in the Facebook Social Graph. When a trigger event occurs to one of those objects, Facebook detects the event 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 Messaging accounts, phone numbers, message templates, and messages sent to your phone numbers.
You must individually subscribe to every Messaging account for which you want to receive webhooks. After fetching the client’s Messaging account ID, subscribe your app to the ID to start receiving webhooks.
See Webhooks for more information about webhooks and fields.

Subscribe to webhooks on a client Messaging account

Use the POST /<WABA_ID>/subscribed_apps endpoint to subscribe your app to webhooks on the business customer’s Messaging account. If you want the customer’s webhooks to be sent to a different callback URL than the one set on your app, you have multiple webhook override options.

Request

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

Response

Upon success:
{
  "success": true
}
Repeat this process for any other Messaging accounts for which you want to receive webhook notifications. If you subscribe your app to webhooks for multiple Messaging accounts, WhatsApp sends all webhook notifications to the app’s callback URL specified in the Webhooks product panel of the App Dashboard, unless you override webhooks.

Get all subscriptions on a Messaging account

Use the Subscribed Apps API to get a list of apps subscribed to webhooks for a Messaging account:

Request syntax

GET https://graph.facebook.com/v26.0/<WABA_ID>/subscribed_apps
A successful response includes an array of apps that have subscribed to the Messaging account, with link, name, and id properties for each app.

Sample request

curl \
'https://graph.facebook.com/v26.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 Messaging account

Use the Subscribed Apps API to unsubscribe your app from webhooks for a Messaging account.

Request syntax

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

Sample request

curl -X DELETE \
'https://graph.facebook.com/v26.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 Messaging accounts. The types of notifications you can subscribe to are:

Available subscription fields

Field name Description
account_alerts
The account_alerts webhook notifies you of changes to a business phone number’s messaging limit, business profile, and Official Business Account status.
account_review_update
The account_review_update webhook notifies you when a WhatsApp account associated with your Messaging account has been reviewed against our policy guidelines. The notification is delivered on the Messaging account, and its entry.id is the Messaging account ID.
account_update
The account_update webhook is delivered on your Messaging account, and notifies of changes to the associated WhatsApp account’s partner-led business verification submission, the Messaging account’s authentication-international rate eligibility, or the WhatsApp account’s primary business location, when the Messaging account is shared with a Solution Partner, policy or terms violations, offboarding, reconnection, or when the Messaging account is deleted.
automatic_events
The automatic_events webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to Automatic Events reporting.
business_capability_update
The business_capability_update webhook notifies you of WhatsApp account hierarchy or business portfolio capability changes (messaging limits, phone number limits, etc.). You receive these notifications through the associated Messaging account, which holds the webhook subscription.
calls
The calls webhook notifies you of call events for user-initiated calls and business-initiated calls, such as when a call is connected or terminated.
history
The history webhook is used to synchronize the WhatsApp Business app chat history of a business customer onboarded by a solution provider.
message_template_components_update
The message_template_components_update webhook notifies you of changes to a template’s components.
message_template_quality_update
The message_template_quality_update webhook notifies you of changes to a template’s quality score.
message_template_status_update
The message_template_status_update webhook notifies you of changes to the status of an existing template.
messages
The messages webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user.
partner_solutions
The partner_solutions webhook describes changes to the status of a Multi-Partner Solution.
payment_configuration_update
The payment_configuration_update webhook notifies you of changes to payment configurations for Payments API India and Payments API Brazil.
phone_number_name_update
The phone_number_name_update webhook notifies you of business phone number display name verification outcomes.
phone_number_quality_update
The phone_number_quality_update webhook notifies you of changes to a business phone number’s throughput level.
security
The security webhook notifies you of changes to a business phone number’s security settings.
smb_app_state_sync
The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider.
smb_message_echoes
The smb_message_echoes webhook notifies you of messages sent via the WhatsApp Business app or a companion (“linked”) device by a business customer who has been onboarded to Cloud API via a solution provider.
template_category_update
The template_category_update webhook notifies you of changes to template’s category.
user_preferences
The user_preferences webhook notifies you of changes to a WhatsApp user’s marketing message preferences.

Examples

Onboarded client

An account_update webhook is triggered with event set to PARTNER_ADDED when a client 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": "495709166956424",
      "time": 1731617831,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "124545784358810",
            "decision": "APPROVED",
            "requested_verified_name": "WhatsApp",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

Quality update received

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "495709166956424",
      "time": 1731617831,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "124545784358810",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

WhatsApp account updates

Sandbox number upgraded to verified account

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "495709166956424",
      "time": 1731617831,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "124545784358810",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

WhatsApp account banned

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "495709166956424",
      "time": 1731617831,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "DATE"
            }
          }
        }
      ]
    }
  ]
}

WhatsApp account review completed

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "495709166956424",
      "time": 1731617831,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

Message template updates

Approved

{
  "entry": [
    {
      "id": "495709166956424",
      "time": 1731617831,
      "changes": [
        {
          "value": {
            "event": "APPROVED",
            "message_template_id": 64244916695,
            "message_template_name": "Summer 20 Template",
            "message_template_language": "en_US",
            "reason": "NONE"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}