Webhooks

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.

For more information, see Webhooks for WhatsApp Business Accounts.

Understanding Webhooks

The types of notifications you can subscribe to are:

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:

account_review_update

Notifies you when a WABA has been reviewed.

Components

You get notifications in the following general format:

{
  "object": "whatsapp_business_account",
  "entry": [
    { // entry object, containing changes
      "changes": [
        { // changes object, containing value
          "value": {
            // value object
          }
        }
      ]
    }
  ]
}

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.

Examples

Here is series of examples that show Webhook notifications you may receive:

Message Template Updates

Approved

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "APPROVED",
              "message_template_id": 1234567, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null 
         }
       }
      ]
    }
  ]
}

Scheduled for Disabling

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "FLAGGED",
              "message_template_id": 1234567, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null,
              "disable_info": {
                  "disable_date": "January 31, 2021",
              }
         }
       }
      ]
    }
  ]
}

Phone Number Updates

Name Update Received

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

Quality Update Received

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243062,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "16505551111",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

WABA Updates

Sandbox Number Upgraded to Verified Account

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505551111",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

WhatsApp Business Account Banned

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "January 31, 2021"
            }
          }
        }
      ]
    }
  ]
}

WhatsApp Business Account Review Completed

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}