Why Discord Webhook Username Override Reverts After Edit Attempt

You edit a Discord webhook message to change the username override, but after saving, the username reverts to the webhook’s default name. This happens because Discord treats username overrides as a one-time attribute applied only when the message is first sent. The webhook system does not allow retroactive changes to the displayed name after the message exists. This article explains the exact technical reason for this behavior and shows you the correct workflow to set a custom username before sending a webhook message.

Why Discord Webhook Username Override Reverts on Edit

Discord webhooks operate on a simple rule: the username override is a property of the message creation event, not a property of the message itself. When you send a webhook message using the Discord API or a bot library, you include a username field in the JSON payload. Discord reads this field once, applies it to the message display, and then discards it. The message object stored on Discord’s servers does not retain the username field as a mutable attribute.

When you edit a webhook message through the Discord client (right-click > Edit Message) or through the API’s edit endpoint, the request body can only modify the content, embeds, components, and attachments fields. The username and avatar_url fields are not part of the edit schema. The API silently ignores any username value sent in an edit request. The displayed name then falls back to the webhook’s default name, which is set in the webhook settings page.

This design prevents abuse where a malicious actor could change a message’s displayed name after it has been seen by users. It also simplifies the message editing logic for developers. The username override is intentionally write-once.

Steps to Set a Custom Webhook Username Before Sending a Message

To display a custom username with a webhook message, you must set the username field at the time you create the message. The following instructions cover both the Discord client method and the API method.

Method 1: Create a Webhook Message with a Custom Username Using the Discord Client

1. Open Server Settings
   Right-click your server icon in the left sidebar and select Server Settings. If you are on mobile, tap the three-dot menu next to the server name and choose Settings.
2. Go to Integrations
   In the left menu, click Integrations. Under the Webhooks section, click View Webhooks.
3. Select the target webhook
   Click the webhook you want to use. In the popup, you will see fields for Name (the default name), Channel, and a Copy Webhook URL button.
4. Send a message with a custom name
   Discord’s client does not provide a built-in interface to set a custom username per message. You must use a third-party tool or a bot that supports the webhook API. For example, use a service like Discohook or a custom script. Paste the webhook URL into the tool, set the Username field to your desired override, write the message content, and click Send.

Method 2: Set the Username Override via the Discord API

1. Obtain the webhook URL
   In Server Settings > Integrations > Webhooks, click the webhook and then click Copy Webhook URL. The URL format is https://discord.com/api/webhooks/{webhook_id}/{token}.
2. Send a POST request with the username field
   Use a tool like curl, Postman, or a programming language of your choice. Send a POST request to the webhook URL with a JSON body containing the username and content fields. Example curl command:
   curl -X POST "https://discord.com/api/webhooks/123456789/abc123def456" -H "Content-Type: application/json" -d '{"username":"My Custom Name","content":"Hello from my webhook!"}'
3. Verify the display
   Check the target channel. The message will display the username you set in the username field. The avatar will default to the webhook’s default avatar unless you also include the avatar_url field.

If the Webhook Username Override Still Does Not Stick

If you followed the steps above but the username still reverts, check these common issues.

You Edited a Message That Already Existed

As explained, editing an existing webhook message cannot change the username. You must delete the old message and send a new one with the desired username. Use the API’s DELETE /webhooks/{id}/{token}/messages/{message_id} endpoint to remove the message, then send a fresh POST request.

You Set the Username in the Webhook Settings Instead of the Message Payload

The Name field in the webhook settings page sets the default name that appears when no username override is provided. Changing this default name affects all future messages that do not include a username field. It does not affect messages that already have a username override. To change the displayed name of an existing message, you must resend it with a new username value.

Your Bot Library Does Not Support Username Override on Edit

Some bot libraries expose a method like edit_message() that accepts a username parameter. The library may send that parameter in the API call, but Discord’s API ignores it. Check your library’s documentation to confirm that the edit method does not claim to support username changes. If it does, the library may be sending the field incorrectly or relying on an outdated API version.

Discord Webhook Message Properties: Create vs Edit

Property	Create (POST)	Edit (PATCH)
username	Accepted, sets display name	Ignored
avatar_url	Accepted, sets avatar	Ignored
content	Accepted	Accepted
embeds	Accepted	Accepted
components	Accepted	Accepted
attachments	Accepted	Accepted

The table above shows that username and avatar_url are write-once fields. You cannot change them after the message is created. To update the displayed name, you must delete the original message and resend it with the new override.

Now you know that the username override is a creation-time attribute. To change it, delete the existing message and send a new one with the correct username field. If you are building a bot that needs to update names regularly, consider storing a mapping of message IDs to desired usernames and automatically resending messages when the name changes. This approach avoids confusion and ensures the correct name always appears.