whatsapp.phone_number.name_updated

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

Triggers

Occurs when a WhatsApp business phone number’s name has been approved or rejected. Subscribe to whatsapp.phone_number.name_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.name_updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPhoneNumber": {
    "id": "<ID>",
    "phoneNumber": "<PHONE_NUMBER>",
    "wabaId": "<WABA_ID>",
    "verifiedName": "<VERIFIED_NAME>",
    "requestedVerifiedName": "<REQUESTED_VERIFIED_NAME>",
    "decision": "<DECISION>",
    "nameStatus": "<NAME_STATUS>",
    "newNameStatus": "<NEW_NAME_STATUS>"
  }
}

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.name_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.
`verifiedName`	string	No	Verified name.
`nameStatus`	string	No	The review status of the current display name request. See also Get Display Name Status. `APPROVED`: The name has been approved. You can download your certificate now. `AVAILABLE_WITHOUT_REVIEW`: The certificate for the phone is available and display name is ready to use without review. `DECLINED`: The name has not been approved. You cannot download your certificate. `EXPIRED`: Your certificate has expire and can no longer be downloaded. `PENDING_REVIEW`: Your name request is under review. You cannot download your certificate. `NONE`: No certificate is available.
`newNameStatus`	string	No	The review status of the new display name request. See also Get Display Name Status. Values: `APPROVED`, `AVAILABLE_WITHOUT_REVIEW`, `DECLINED`, `EXPIRED`, `PENDING_REVIEW`, `NONE`.
`decision`	string	No	Review decision made on this phone number. One of `APPROVED` or `REJECTED`.
`requestedVerifiedName`	string	No	Last requested verified name.
`rejectionReason`	string	No	Rejection reason.

Example

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

{
  "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": "+12025550124",
    "wabaId": "whatsapp-business-account-id",
    "verifiedName": "Example business",
    "requestedVerifiedName": "Example business",
    "decision": "APPROVED",
    "nameStatus": "APPROVED",
    "newNameStatus": "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.phone_number.name_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