whatsapp.business_account.updated

Use whatsapp.business_account.updated to handle this event at your webhook endpoint.

Triggers

Occurs when a policy violation happened, WhatsApp Business Account has been banned and more. Subscribe to whatsapp.business_account.updated when you configure your webhook endpoint.

Syntax

YCloud sends an HTTP POST request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under Parameters. Optional fields and other variants are described below.

{
  "id": "<ID>",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappBusinessAccount": {
    "id": "<ID>",
    "name": "<NAME>",
    "updateEvent": "<UPDATE_EVENT>",
    "violationType": "<VIOLATION_TYPE>",
    "restrictions": [
      {
        "restrictionType": "<RESTRICTION_TYPE>",
        "expiration": "<EXPIRATION>"
      }
    ]
  }
}

Parameters

Validate the YCloud-Signature HTTP header before you process the JSON body. See signature validation.

Event envelope

Parameter	Type	Required	Description
`id`	string	Yes	Unique ID for the event. Minimum length: `6`. Maximum length: `128`.
`type`	string	Yes	Always `whatsapp.business_account.updated`.
`apiVersion`	string	Yes	The API version used to render this event.
`createTime`	string (date-time)	Yes	The time at which this event was created, formatted in RFC 3339. e.g., `2022-06-01T12:00:00.000Z`.

Event payload

Parameter	Type	Required	Description
`whatsappBusinessAccount`	object	No	Event-specific `whatsappBusinessAccount` payload.

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, Required applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

whatsappBusinessAccount

Parameter	Type	Required	Description
`id`	string	No	WhatApp Business Account ID.
`name`	string	No	User-friendly name to differentiate WhatsApp Business Accounts.
`accountReviewStatus`	string	No	WhatsApp Business Account review status. Values: `PENDING`, `APPROVED`, `REJECTED`.
`updateEvent`	string	No	Indicates the update event type of the WABA when a notification is sent to you to report a policy violation, a WABA has been banned and more. `DISABLED_UPDATE`: WhatsApp Business Account Banned. `ACCOUNT_RESTRICTION`: WhatsApp Business Account Restricted Due To Policy Violations. `ACCOUNT_VIOLATION`: WhatsApp Business Account Violates Policy. `PARTNER_REMOVED`: WhatsApp Business Account was removed from the partner connection. `PARTNER_APP_UNINSTALLED`: WhatsApp Business Account partner app was uninstalled. `AUTH_INTL_PRICE_ELIGIBILITY_UPDATE`: WhatsApp Business Account is eligible for the authentication-international rate. `BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE`: Business’s primary business location is set. `BUSINESS_CAPABILITY_UPDATE`: Meta reported a change to the Business Portfolio or WABA phone-number registration limit.
`banState`	string	No	The ban state of the WhatsApp Business Account. Values: `SCHEDULE_FOR_DISABLE`, `DISABLE`, `REINSTATE`.
`banDate`	string	No	The date when the WABA is banned.
`violationType`	string	No	Used to report violations imposed on the WABA. See Meta’s Policy enforcement violations for violation types and descriptions. Meta may update this list over time. For Utility Direct Send violation types and restriction details, see Meta’s Webhook for account restriction.
`restrictions`	object[]	No	Used to report restrictions imposed on the WABA, when that WABA violates WhatsApp Business Platform policies.
`maxPhoneNumbersPerBusiness`	integer (int32)	No	Included in a `whatsapp.business_account.updated` webhook with `updateEvent=BUSINESS_CAPABILITY_UPDATE` when Meta reports the Business Portfolio phone-number registration limit. Meta currently reports this field separately from `maxPhoneNumbersPerWaba`, but consumers must process both if a future update includes them together.
`maxPhoneNumbersPerWaba`	integer (int32)	No	Included in a `whatsapp.business_account.updated` webhook with `updateEvent=BUSINESS_CAPABILITY_UPDATE` when Meta reports the WABA phone-number registration limit. Meta currently reports this field separately from `maxPhoneNumbersPerBusiness`, but consumers must process both if a future update includes them together.
`authIntlRateEligibilityCountries`	object[]	No	Starting June 1, 2024, we are updating our authentication rate card and introducing a new authentication-international rate. This rate will apply in the the following countries: June 1, 2024 – Indonesia (country calling code +62, country code `ID`) July 1, 2024 – India (country calling code +91, country code `IN`) See also Authentication-International Rates.
`primaryBusinessLocation`	string	No	Your primary business location is the country where your business is based. It will appear in the Business Manager under the Primary Business Location field starting May 1, 2024. ISO 3166-1 alpha-2 country code.

whatsappBusinessAccount.restrictions[]

Parameter	Type	Required	Description
`restrictionType`	string	No	Restriction type. Values: `RESTRICTED_ADD_PHONE_NUMBER_ACTION`, `RESTRICTED_BIZ_INITIATED_MESSAGING`, `RESTRICTED_CUSTOMER_INITIATED_MESSAGING`, `RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES`.
`expiration`	string (date-time)	No	The time at which this restriction expires, formatted in RFC 3339. e.g., `2022-06-01T12:00:00.000Z`.

whatsappBusinessAccount.authIntlRateEligibilityCountries[]

Parameter	Type	Required	Description
`countryCode`	string	No	ISO 3166-1 alpha-2 country code.
`startTime`	string (date-time)	No	Date when newly-opened authentication conversations are subject to authentication-international rates, formatted in RFC 3339. e.g., `2024-07-01T00:00:00.000Z`.

Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

Utility Direct Send restriction event

Meta restricted Utility Direct Send for 7 days after repeated category misuse.

{
  "id": "evt_direct_send_restriction_123",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
        "expiration": "2026-09-24T08:00:00.000Z"
      }
    ]
  }
}

Authentication-International Rate Eligibility

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

Primary Business Location Update

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

Phone-number registration limit update

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

Account violation

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SCAM"
  }
}

Account Restriction

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      }
    ]
  }
}

Account Disabled

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

Account Reinstate

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

After verifying the signature and durably accepting the event, return a 2xx response. Process slow work asynchronously.

HTTP/1.1 200 OK

For scenario walkthroughs, see annotated examples.

Getting Started

Guides

Endpoints

Webhook reference

whatsapp.business_account.updated

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappBusinessAccount

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​whatsappBusinessAccount

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappBusinessAccount

Example