WhatsApp Business Platform > Business Management API > Reference

Webhooks Components

Webhooks have a top level array field indicating what is being communicated. The members of the array are JSON objects with detailed fields relevant to the Webhook.

WhatsApp Business Management API webhooks can contain the following objects:

Parameter Description

Parameter	Description
`object`	This is the object that was subscribed to. For embedded signup, this is always `whatsapp_business_account`.
`entry`	This object contains the details of the change that triggered the webhooks call.

object

This is the object that was subscribed to.

For embedded signup, this is always whatsapp_business_account.

entry

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

The `entry` Object

Parameter	Description
`id`	ID of Whatsapp Business Accounts this webhook belongs to.
`time`	Time for the entry.
`changes`	Changes that triggered the webhooks call —see `changes` object.

`changes`

Parameter	Description (Click the arrow in the left column for supported values.)
`field`	Contains the type of notification you are getting on that webhook.
Supported Values	`account_alerts` `account_review_update` `account_update` `business_capability_update` `message_template_quality_update` `message_template_status_update` `phone_number_name_update` `phone_number_quality_update` `security` `template_category_update`
`value`	Contains details of the changes related to the specified `field` —see `value` object.

`value`

Parameter	Description (Click the arrow in the left column for supported values.)
`ban_info`	Added to webhooks when an account has been banned. This object includes two properties: `waba_ban_state`: Options are: `DISABLE` `REINSTATE` `SCHEDULE_FOR_DISABLE` `waba_ban_date`
`current_limit`	Contains the current tier limit where this account is.
Supported Values	`TIER_50` `TIER_250` `TIER_1K` `TIER_10K` `TIER_100K` `TIER_UNLIMITED`
`decision`	Used if a decision about accounts or phone numbers has been made.
Supported Values	`APPROVED` `REJECTED`
`display_phone_number`	Includes the display phone number of the business account account that triggered the notification.
`event`	Used when an event happened in a specific WABA. Click the arrow on the left column to see all available options.
Display name updates	`APPROVED`: The review was approved. If a business was previously unable to download their certificate, that business should now be able to use their display name by downloading the certificate. `DEFERRED`: The review is deferred and the business can use their display name by downloading the certificate. `REJECTED`: The review was rejected, with the given rejection reason. If a business was previously unable to download their certificate, that business needs to reapply for a display name review to get access to the certificate. If a business is already using their certificate, the display name review rejection does not affect their operation. However, passing the review is necessary for the business to grow its message and account limits.
Message template quality update	Previous quality score: `GREEN` `RED` `UNKNOWN` `YELLOW` New quality score: `GREEN` `RED` `UNKNOWN` `YELLOW`
Message template status updates	`APPROVED` `DISABLED` `IN_APPEAL` `PENDING` `REINSTATED` `REJECTED` `FLAGGED`
Phone number updates	`DOWNGRADE` `FLAGGED` `ONBOARDING` `UNFLAGGED` `UPGRADE`
Template Category Update	Previous categories: `MARKETING` `OTP` `TRANSACTIONAL` New categories: `AUTHENTICATION` `MARKETING` `UTILITY`
Two-step verification code	`PIN_CHANGED:` Two-step verification code is updated (Cloud API only) `PIN_RESET_REQUEST:` Request to disable Two-step verification code `PIN_RESET_SUCCESS:` Two-step verification code is disabled
WABA updates	`ACCOUNT_RESTRICTION`: Used to report that a restriction has been put in place when a WABA violates WhatsApp Business Platform policies. `DISABLED_UPDATE` `VERIFIED_ACCOUNT`
`max_daily_conversation_per_phone`	Always present when `field=business_capability_update`. Indicates the number of template messages you can send with each of your WhatsApp Business Account's business phone numbers that have an approved display name. See Messaging Limits.
`max_phone_numbers_per_business`	Includes the maximum number of phone numbers that can belong to a business. When field=business_capability_update, a webhook will have either max_phone_numbers_per_business or max_phone_numbers_per_waba present.
`max_phone_numbers_per_waba`	Includes the maximum number of phone numbers that can belong to a WABA. When field=business_capability_update, a webhook will have either max_phone_numbers_per_business or max_phone_numbers_per_waba present.
`reason`	Template rejection reason. Possible values: `ABUSIVE_CONTENT` — Content has been determined to be abusive. `INCORRECT_CATEGORY` — Category has been determined to be incorrect. See Template Categories. `INVALID_FORMAT` — Duplicate content or missing examples. `NONE` - Default, set when template is approved. `SCAM` — Content has been determined to be a scam.
`rejection_reason`	If a request was rejected, this field displays the reason for that rejection.
`requested_verified_name`	This field displays the name that was sent to be verified.
`restriction_info` enum	Used to report restrictions imposed on a specific WABA, when that WABA violates WhatsApp Business Platform policies. This field includes a list of restriction types and their corresponding expiration dates. Possible restriction types are: `RESTRICTED_ADD_PHONE_NUMBER_ACTION` `RESTRICTED_BIZ_INITIATED_MESSAGING` `RESTRICTED_CUSTOMER_INITIATED_MESSAGING` Expiration dates are provided in DateTime format.
`requester`	ID of the user who requested to disable, or has already disabled or updated, the two-step verification code.

Examples

Message Template Status Update

Template Approved

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "APPROVED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "NONE"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Template Rejected

{
  "object": "whatsapp_business_account"
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "REJECTED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "<REJECTION_REASON>"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ]
}

Template Scheduled for Disabling

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "FLAGGED",
              "message_template_id": TEMPLATE-ID, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null,
              "disable_info": {
                  "disable_date": "DATE",
              }
         }
       }
      ]
    }
  ]
}

Template Paused

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10908...",
      "time": 1661885238,
      "changes": [
        {
          "value": {
            "event": "PAUSED",
            "message_template_id": 6048...,
            "message_template_name": "welcome",
            "message_template_language": "en_US",
            "reason": "NONE",
            "other_info": {
              "title": "SECOND_PAUSE",
              "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Template Message Pending Deletion

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10310...",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "PENDING_DELETION",
            "message_template_id": 1137...,
            "message_template_name": "<MY_TEMPLATE_NAME>",
            "message_template_language": "en_US",
            "reason": "NONE"            
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Template Category Update

Template Category Changed

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<ID>",
      "time": <TIME>,
      "changes": [
        {
          "field": "template_category_update",
          "value": {            
            "message_template_id": <MESSAGE_TEMPLATE_ID>,
            "message_template_name": "<MESSAGE_TEMPLATE_NAME>",
            "message_template_language": "<MESSAGE_TEMPLATE_LANGUAGE",
            "previous_category": "<PREVIOUS_CATEGORY>",
            "new_category": "<NEW_CATEGORY>"
          }
        }
      ]
    }
  ]
}

Message Template Quality Update

Template Quality Rating Changed

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "field": "message_template_quality_update",
          "value": {
            "previous_quality_score": "<PREVIOUS_QUALITY_SCORE>",
            "new_quality_score": "<NEW_QUALITY_SCORE>",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>"
          }
        }
      ]
    }
  ]
}

Phone Number Updates

Name Update Received

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "PHONE_NUMBER",
            "decision": "APPROVED",
            "requested_verified_name": "WhatsApp",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

Quality Update Received

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "PHONE_NUMBER",
            "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": TIMESTAMP,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "PHONE_NUMBER",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

WhatsApp Business Account Banned

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "DATE"
            }
          }
        }
      ]
    }
  ]
}

WhatsApp Business Account Violates Policy

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "VIOLATION_TYPE"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business Account Restricted After Policy Violation

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
               {"restriction_type": 
                 "RESTRICTED_BIZ_INITIATED_MESSAGING" | 
                 "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION" | 
                 "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", 
                 "expiration": TIMESTAMP}
                 ]
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business Account Disabled

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "DISABLED_UPDATE",
            "ban_info": {
              "waba_ban_state": 
               "SCHEDULE_FOR_DISABLE" | 
               "DISABLE" | 
               "REINSTATE",
               "waba_ban_date": TIMESTAMP
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business Account Review Completed

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

WhatsApp Business Account Restricted Due To Policy Violations

{
  "field": "account_update",
  "value": {
    "phone_number": "PHONE_NUMBER",
    "event": "ACCOUNT_RESTRICTION",
    "restriction_info": [
      {
        "restriction_type": "RESTRICTION_ADD_PHONE_NUMBER_ACTION",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      }
    ]
  }
}

WhatsApp Business Account Deleted

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "ACCOUNT_DELETED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

WhatsApp Business Account Removed from Partner

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "PARTNER_REMOVED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

Business Capability Updates

{
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
        "time": TIMESTAMP,
        "changes": [
          {
            "field": "business_capability_update",
            "value": {
              "max_daily_conversation_per_phone": NUMBER,
              "max_phone_numbers_per_business": NUMBER
            }
          }
        ]
      }
    ]
  }

Account Alerts

Messaging limit increase denied

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "CRITICAL",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_FAILED",
            "alert_description": "Based on your activity, limits cannot be increased for your business <BUSINES_NAME>. Contact support for more information."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Messaging limit increase denied, more usage required

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
            "alert_description": "Limits cannot be increased for your business <BUSINES_NAME>. Use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Messaging limit increase denied, need more info

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO",
            "alert_description": "Additional verification is required for your business <BUSINESS_NAME>. Go to Security Center in Meta for Business to complete identity verification. To continue without completing additional verification, your business can use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

WhatsApp Business Platform | Cloud API | On-Premises API | Business Management API