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's display name is reviewed.A business phone number's already approved display name is edited and reviewed.

    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'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's name or employee identifier.
    NAME_ENDCLIENT_NOTRELATED - Rejected because the display name included an unrelated 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's name or employee identifier. NAME_NOT_CONSISTENT - Rejected because the display name was not consistent with the 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
    Back to top