WhatsApp account and phone number webhook examples

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

What it is

Handle business account review, update, and deletion events, plus phone-number deletion, display-name review, quality, and Business Username updates. Route each payload by its exact event type: account events use whatsappBusinessAccount, while phone-number events use whatsappPhoneNumber.

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.

Account deletion

Use whatsapp.business_account.deleted to handle a WhatsApp Business Account deletion event. Read whatsappBusinessAccount.id to identify the affected WABA.

Request

{
  "id": "evt_business_account_deleted_123",
  "type": "whatsapp.business_account.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "removedReason": "ACCOUNT_DISCONNECTED",
    "removedInitiatedBy": "USER",
    "removedTime": "2026-05-26T12:00:00.000Z"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

The removal fields appear directly inside whatsappBusinessAccount when available.

Field	Meaning
`id`	The affected WhatsApp Business Account ID.
`removedReason`	The raw removal reason. See the known values below.
`removedInitiatedBy`	`USER` for removal initiated by the WhatsApp user, or `SYSTEM` for removal initiated by Meta.
`removedTime`	The time YCloud received the deletion event, in RFC 3339 format.

Known removedReason values include:

Value	Meaning
`ACCOUNT_DISCONNECTED`	The account was disconnected due to enforcement or because the WhatsApp account was explicitly deleted.
`BUSINESS_DOWNGRADE`	The phone number was registered with the consumer WhatsApp app.
`CHANGE_NUMBER`	The WhatsApp phone number was changed.
`COMPANION_INACTIVITY`	A companion device was inactive for approximately 30 days.
`PRIMARY_INACTIVITY`	A primary device was inactive for approximately 30 days.
`USER_RE_REGISTERED`	WhatsApp was re-registered on a new device.

Preserve unknown reason and initiator values. Deduplicate deliveries by the event id, and tolerate omitted removal fields.

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

When you receive a whatsapp.business_account.updated event with whatsappBusinessAccount.updateEvent set to ACCOUNT_VIOLATION, inspect whatsappBusinessAccount.violationType to identify the reported policy violation. See Meta’s Policy enforcement violations for violation types and descriptions. Meta may update this list over time. 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": "SCAM"
  }
}

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. For Utility Direct Send, see Direct Send notifications for a YCloud ACCOUNT_RESTRICTION payload. See Meta’s Webhook for account restriction for Direct Send-specific violation types and restriction details. 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.

Utility Direct Send restriction

You receive whatsapp.business_account.updated when Meta restricts Utility Direct Send after repeated category misuse. This example shows a seven-day restriction.

Request

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

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Use whatsappBusinessAccount.id to identify the affected WABA and pause its Utility Direct Send workflow. Read violationType for the reason, restrictions[].restrictionType for the affected capability, and restrictions[].expiration for the expiry when supplied. A successful review of one template does not automatically lift an account-level restriction. See Direct Send restrictions and notifications.

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.

Business account review

Use whatsapp.business_account.reviewed when a WhatsApp Business Account has been reviewed.

Request

{
  "id": "evt_example_whatsapp_business_account_reviewed",
  "type": "whatsapp.business_account.reviewed",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "decision": "APPROVED",
    "accountReviewStatus": "APPROVED"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Identify the WABA with id. Read decision for the review decision (APPROVED or REJECTED) and accountReviewStatus for the account review status when supplied. Do not route this event as whatsapp.business_account.updated.

Phone number deletion

Use whatsapp.phone_number.deleted when a WhatsApp business phone number is deleted.

Request

{
  "id": "evt_example_whatsapp_phone_number_deleted",
  "type": "whatsapp.phone_number.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Use whatsappPhoneNumber.id to identify the deleted phone number and wabaId to associate it with its account. This is a phone-number event; do not treat it as deletion of the entire WABA.

Phone number display-name review

Use whatsapp.phone_number.name_updated when a business phone number display name is approved or rejected.

Request

{
  "id": "evt_example_whatsapp_phone_number_name_updated",
  "type": "whatsapp.phone_number.name_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id",
    "verifiedName": "Example business",
    "requestedVerifiedName": "Example business",
    "decision": "APPROVED",
    "nameStatus": "APPROVED",
    "newNameStatus": "APPROVED"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Read decision and the supplied name-status fields. newNameStatus describes the new display-name request, requestedVerifiedName identifies the last requested name, and rejectionReason describes a rejection when present. Display-name review is separate from a Business Username update.

Phone number quality update

Use whatsapp.phone_number.quality_updated for changes to a business phone number’s quality-related status.

Request

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Read qualityRating (GREEN, YELLOW, or RED) and qualityUpdateEvent to understand the update. messagingLimit is the phone-number tier; whatsappBusinessManagerMessagingLimit is the owning business portfolio’s limit. Keep these fields separate and update only the values supplied in the event.

Business Username activated

Use whatsapp.phone_number.business_username_updated to synchronize a phone number’s Business Username.

Request

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

businessUsername is the active username without a leading @. Read businessUsernameStatus and businessUsernameUpdatedAt with the phone-number id. Do not confuse this value with the verified display name.

Business Username request reserved

An active Business Username can remain in use while a replacement request is reserved.

Request

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

In this example, businessUsername remains acme.support while requestedBusinessUsername is acme.help. The reserved status describes the pending request, not activation of the replacement. Accept the legacy pending_review value when reading older events; new writes use reserved.

​What it is

​Before you begin

​How it works

​Request

​Response

​Account deletion

​Request

​Response

​Explanation

​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

​Utility Direct Send restriction

​Request

​Response

​Explanation

​Account Disabled

​Request

​Response

​Explanation

​Account Reinstate

​Request

​Response

​Explanation

​Business account review

​Request

​Response

​Explanation

​Phone number deletion

​Request

​Response

​Explanation

​Phone number display-name review

​Request

​Response

​Explanation

​Phone number quality update

​Request

​Response

​Explanation

​Business Username activated

​Request

​Response

​Explanation

​Business Username request reserved

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Account deletion

Request

Response

Explanation

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

Utility Direct Send restriction

Request

Response

Explanation

Account Disabled

Request

Response

Explanation

Account Reinstate

Request

Response

Explanation

Business account review

Request

Response

Explanation

Phone number deletion

Request

Response

Explanation

Phone number display-name review

Request

Response

Explanation

Phone number quality update

Request

Response

Explanation

Business Username activated

Request

Response

Explanation

Business Username request reserved

Request

Response

Explanation