WhatsApp Business Account Updated Webhook Examples

For the exhaustive schema-derived catalog, see all examples.

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/1.1 200 OK

For endpoint setup, signature validation, and retry behavior, see Configure webhooks.

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 . 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

{
  "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/1.1 200 OK

If a message is billed at the authentication-international rate, the whatsappMessage.pricingCategory in whatsapp.message.updated webhooks will be set to authentication_international. Here is an example:

{
  "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 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

{
  "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/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

{
  "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/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
. Here is an example:

Request

{
  "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/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

{
  "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/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

{
  "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/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

{
  "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/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.

Getting Started

Guides

Endpoints

Webhooks

WhatsApp Business Account Updated Webhook Examples

What it is

Before you begin

How it works

Request

Response

Authentication-International Rate Eligibility

Request

Response

Explanation

Primary Business Location Update

Request

Response

Explanation

Phone-number registration limit update

Request

Response

Explanation

Account Violation

Request

Response

Explanation

Account Restriction

Request

Response

Explanation

Account Disabled

Request

Response

Explanation

Account Reinstate

Request

Response

Explanation

​What it is

​Before you begin

​How it works

​Request

​Response

​Authentication-International Rate Eligibility

​Request

​Response

​Explanation

​Primary Business Location Update

​Request

​Response

​Explanation

​Phone-number registration limit update

​Request

​Response

​Explanation

​Account Violation

​Request

​Response

​Explanation

​Account Restriction

​Request

​Response

​Explanation

​Account Disabled

​Request

​Response

​Explanation

​Account Reinstate

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Authentication-International Rate Eligibility

Request

Response

Explanation

Primary Business Location Update

Request

Response

Explanation

Phone-number registration limit update

Request

Response

Explanation

Account Violation

Request

Response

Explanation

Account Restriction

Request

Response

Explanation

Account Disabled

Request

Response

Explanation

Account Reinstate

Request

Response

Explanation