whatsapp.phone_number.business_username_updated

Use whatsapp.phone_number.business_username_updated to handle this event at your webhook endpoint.

Triggers

Occurs when a WhatsApp business phone number’s Business Username is updated. Subscribe to whatsapp.phone_number.business_username_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.phone_number.business_username_updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPhoneNumber": {
    "id": "<ID>",
    "wabaId": "<WABA_ID>",
    "phoneNumber": "<PHONE_NUMBER>",
    "businessUsername": "<BUSINESS_USERNAME>",
    "businessUsernameStatus": "<BUSINESS_USERNAME_STATUS>",
    "businessUsernameContext": "<BUSINESS_USERNAME_CONTEXT>"
  }
}

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.phone_number.business_username_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
`whatsappPhoneNumber`	object	No	Event-specific `whatsappPhoneNumber` 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.

whatsappPhoneNumber

Parameter	Type	Required	Description
`id`	string	No	Phone number ID.
`phoneNumber`	string	No	Phone number in E.164 format.
`displayPhoneNumber`	string	No	Display phone number.
`wabaId`	string	No	WhatsApp Business Account ID.
`businessUsername`	string	No	Active Business Username for this phone number. The value is a plain username without `@`.
`businessUsernameStatus`	string	No	Business Username state for a WhatsApp business phone number. `not_set`: No active or pending Business Username exists. `active`: A Business Username is active. `reserved`: A requested Business Username is reserved by Meta and may still be under review. `pending_review`: Legacy compatibility value for an under-review request. New writes use `reserved`. If an active username exists while a new request is reserved or under review, `businessUsernameStatus` is `reserved`, `businessUsername` contains the still-active username, and `requestedBusinessUsername` contains the requested username.
`requestedBusinessUsername`	string	No	Last requested Business Username that is still under review. This value can coexist with an active `businessUsername` while the new request is pending.
`businessUsernameContext`	string	No	Optional context for this username notification. `revoked` appears only when the username returned by a successful current Meta query matches this revocation notification. Omitted for an obsolete revocation or a notification without context. This field does not expose historical page warnings.
`businessUsernameUpdatedAt`	string (date-time)	No	The time when the Business Username state was last updated.

Example

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

Business username revoked and replaced

{
  "id": "evt_business_username_revoked_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "wabaId": "whatsapp-business-account-id",
    "phoneNumber": "+12025550124",
    "businessUsername": "autogenerated_name",
    "businessUsernameStatus": "active",
    "businessUsernameContext": "revoked"
  }
}

WhatsApp phone number Business Username updated event

Example payload when a WhatsApp phone number Business Username becomes active

{
  "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": "+12025550124",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

WhatsApp phone number Business Username reserved event

Example payload when a WhatsApp phone number has a reserved Business Username 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": "+12025550124",
    "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"
  }
}

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

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappPhoneNumber

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​whatsappPhoneNumber

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappPhoneNumber

Example