WhatsApp Business Management API

Webhooks Setup

Subscribe Webhooks to get notifications for changes to your WhatsApp Business Account settings and quality signals.

Webhooks set up will not affect the phone number on your WhatsApp Business App. Only after you migrate your number over to the WhatsApp Business Platform can you no longer use that number on your WhatsApp Business App.

Create an Endpoint

Before you can start receiving notifications you will need to create an endpoint on your server to receive notifications.

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

Learn more about Verifying Requests and Event Notifications

Subcribe to Webhooks

To subscribe to Webhooks, you will need to get a Meta App ID and permissions. To do this go to the Meta App Dashboard. There you will:

  1. Create a Meta App in the Meta App Dashboard
  2. Add the Webhooks Product to your Meta app in the App Dashboard

    At any time, each Meta App can have only one endpoint configured. If you need to send your webhook updates to multiple endpoints, you need multiple Meta Apps.

When you are ready to scale your business messaging, you may need to:

  1. Add the whatsapp_business_management permission in your App Dashboard
  2. Successfully complete Meta App Review – This step will take time but you can continue to test during the entire review process.

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.

    Notification Payload

    All notifications have the following generic format:

    [{
    "object": "whatsapp_business_account",
    "entry": [{
       "id": "{whatsapp-business-account-id}",
        "time": {unix-timestamp},
        "changes": [{
            "field": "{subscribed-field}",
            "value": {
                # Information that was update
            }
          }]
      }]
  }]

    The top level array contains two main objects:

    ParameterDescription

    object

    This is the object that was subscribed to.

    entry

    This object contains the details of the change that triggered the webhooks call.

    See Components for all available webhooks objects.

    Sample App Endpoints