phone_number_name_update Webhook

The phone_number_name_update field reports the outcome of Meta's review of a business phone number's display name. It is a management webhook field, not a message-path field.

What phone_number_name_update Reports

Each event identifies the phone number by its display number and carries the review decision, the requested_verified_name, and a rejection_reason when the name was rejected.

When It Fires

Meta sends it when:

• the display name of a newly created business phone number is reviewed,
• an already approved display name is edited and the new name is reviewed.

Payload Shape

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "time": 1739321024,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "15550783881",
            "decision": "APPROVED",
            "requested_verified_name": "Lucky Shrub",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

requested_verified_name is the name collected when the number was created, or the new name submitted when editing an approved one.

Decision and Rejection Values

See Display Names for naming rules and common rejection causes.

Dualhook Handling

Dualhook subscription: subscribed and forwarded. Dualhook's Meta app subscribes to phone_number_name_update. Meta does not allow Webhook Override for this field, so it arrives on Dualhook's app-level callback and Dualhook forwards it to your endpoint with X-Dualhook-* headers.

Dualhook records each event in the connection's webhook log as a name update. Dualhook does not edit display names, except that the Health Report can submit one for a Cloud API number that has no approved name (see Display Names). Make other changes in WhatsApp Manager. The payload contains account metadata only, never message content.

Implementation Notes

• Match the event to a phone number by display_phone_number and the WABA ID in entry[].id. The payload has no phone number ID.
• Treat rejection_reason as nullable. It is null for accepted names.
• Do not treat PENDING or DEFERRED as final. Wait for a later APPROVED or REJECTED event.
• After APPROVED for a number that is already registered, re-register it with POST /<PHONE_NUMBER_ID>/register within 14 days to apply the new name. Otherwise the name must be submitted for review again.
• A pending or rejected name does not by itself mean the number is disconnected, but it can limit how the business appears to users.

Related

• Webhook Subscription Fields
• Webhook Events & Notifications
• Display Names
• Official Business Account
• Phone Numbers