Skip to main content

phone_number_name_update webhook reference | Developer Documentation

phone_number_name_update webhook reference

Updated: Oct 22, 2025
This reference describes trigger events and payload contents for the WhatsApp Business Account phone_number_name_update webhook.
The phone_number_name_update webhook notifies you of business phone number display name verification outcomes.

Triggers

    A newly created business phone number’number's display name is reviewed.A business phone number’number's already approved display name is edited and reviewed.

    Syntax

    

    {
    
"entry":
    
[
    
{
    
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <WEBHOOK_TRIGGER_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
            "decision": "<DECISION>",
            "requested_verified_name": "<REQUESTED_DISPLAY_NAME>",
            "rejection_reason": "<REJECTION_REASON>"
          },
          "field": "phone_number_name_update"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}
    Parameters
    

    

    



Placeholder 

Description 

Example value 




    

    <BUSINESS_DISPLAY_PHONE_NUMBER>
    

    String
    


    

    Business display phone number.
    


    

    15550783881
    



    

    <DECISION>
    

    String
    


    

    Indicates the outcome of the business phone number display name verification process.
    

    APPROVED —- Indicates the display name has been approved and will now appear at the top of the business phone number’number's profile in the WhatsApp client.
    

    DEFERRED —- Indicates a decision has been deferred.
    

    PENDING —- Indicates a decision is still pending further review.
    

    REJECTED —- Indicates the display name has been rejected. You can edit the name using WhatsApp Manager⁠?. Review our display name guidelines⁠? before editing.
    


    

    APPROVED
    



    

    <REJECTION_REASON>
    

    String
    


    

    The reason why the business phone number display name was rejected, if it was rejected. Review our display name guidelines for common rejection reasons.
    

    Values can be:
    

    NAME_EMPLOYEE_ISSUE —- Rejected because the display name included a person’person's name or employee identifier.
    

    NAME_ENDCLIENT_NOTRELATED —- Rejected because the display name included an unrelated business’business's name.
    

    NAME_FORMAT_UNACCEPTABLE —- Rejected because the display name used an unacceptable format.
    

    NAME_INDIVIDUAL_ISSUE —- Rejected because the display name included a person’person's name or employee identifier. NAME_NOT_CONSISTENT —- Rejected because the display name was not consistent with the business’business's branding.
    

    null —- Indicates name was accepted.
    

    UNKNOWN —- Rejected for an unknown reason. Please contact support.
    


    

    APPROVED
    



    

    <REQUESTED_DISPLAY_NAME>
    

    String
    


    

    The business phone number display name collected when the number was created, or name submitted when editing an already approved display name.
    


    

    Lucky Shrub
    



    

    <WEBHOOK_TRIGGER_TIMESTAMP>
    

    Integer
    


    

    Unix timestamp indicating when the webhook was triggered.
    


    

    1739321024
    



    

    <WHATSAPP_BUSINESS_ACCOUNT_ID>
    

    String
    


    

    WhatsApp Business Account ID.
    


    

    102290129340398
    

    

    

    

    Example
    

    

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

            
    
        
    
    
    

    
    

    
    
    
        
    
             Back to top