> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Business Account Updated Webhook Examples

> Handle WhatsApp business account update events.

<Note>For the exhaustive schema-derived catalog, see [all examples](/en/api-reference/guides/examples/webhook-examples/webhook-payload-examples).</Note>

## What it is

Handle WhatsApp business account update events.

## Before you begin

* Create a public HTTPS endpoint in your application.
* Configure a YCloud webhook endpoint for the event types you need.
* Store the endpoint signing secret securely.
* Make event processing idempotent.

## How it works

YCloud sends an HTTP `POST` request when the event occurs. Verify the signature, durably record the event, return a `2xx` response, and process slow work asynchronously.

## Request

The scenarios below show requests delivered to your webhook URL. Treat the event `id` as the delivery identifier and use `type` to route the payload.

## Response

Return a `2xx` status after accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>For endpoint setup, signature validation, and retry behavior, see [Configure webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks).</Note>

## Authentication-International Rate Eligibility

Starting June 1, 2024, we are 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`)

For more information, see [Authentication-International Rate Eligibility](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates#eligibility) .

A `whatsapp.business_account.updated` webhook will be triggered if your business is deemed eligible for international rates. The webhook will include start times for each country that has an authentication-international rate.

### Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
      }
    ]
  }
}
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

If a message is billed at the authentication-international rate, the `whatsappMessage.pricingCategory` in [whatsapp.message.updated](/en/api-reference/webhooks/test-webhooks#whatsappmessageupdated) webhooks will be set to `authentication_international`.

Here is an example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Primary Business Location Update

Your [primary business location](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates#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.

If Meta is able to determine the country where your business is based, we will trigger an `whatsapp.business_account.updated` webhook with the country's two-digit code.

Here is an example:

### Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
  }
}
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Phone-number registration limit update

Meta sends a business capability update for a WABA when the corresponding Business Portfolio or WABA phone-number registration limit changes. YCloud delivers it as `whatsapp.business_account.updated` with `updateEvent=BUSINESS_CAPABILITY_UPDATE`.

The webhook is WABA-level: `whatsappBusinessAccount.id` is the WABA ID from the Meta webhook entry. Meta currently reports `maxPhoneNumbersPerBusiness` and `maxPhoneNumbersPerWaba` in separate updates. Do not treat them as mutually exclusive: process each field independently and accept both if a future update includes them together. A value of `0` is valid.

Here is an example of a WABA phone-number limit update:

### Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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
  }
}
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and update only the limit field included in the payload.

## Account Violation

WhatsApp Business Accounts will initially get a warning with information on the policy they violated. See also [WhatsApp Business Platform Policy Violations<br />
](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/violations).

Here is an example:

### Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SPAM"
  }
}
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Account Restriction

If Business Accounts repeatedly violate the WhatsApp Business Terms of Service or high-risk policy categories such as sending spam, adult content, sale of alcohol and tobacco, drugs, gambling and unsafe supplements, they may start seeing messaging restrictions that gradually increase in duration.

Here is an example:

### Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
      },
    ]
  }
}
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Account Disabled

WhatsApp Business Accounts may be disabled if the business does not make changes after multiple warnings and feature limits or blocks.

Here is an example:

### Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
  }
}
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Account Reinstate

You can appeal the WhatsApp Business Account ban decision to reinstate it. Once approved, the account review status changes to `APPROVED`.

Here is an example:

### Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
  }
}
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.