Discord Webhook Username Override: How to Customize

When you send messages through a Discord webhook, the default sender name is usually the webhook name you set when creating it. You might want to display a different name for each automated message, such as a weather bot showing “Weather Bot” or a game server showing “Server Status”. Discord allows you to override the webhook username on a per-message basis using the webhook API. This article explains how to set a custom username when sending webhook messages using the username field in the JSON payload.

How Discord Webhook Username Override Works

A Discord webhook is a simple way to send automated messages to a text channel. When you create a webhook in a server, you give it a default name and avatar. Every message sent through that webhook normally uses that default name and avatar. However, the webhook API lets you change the username and avatar for each individual message by including the username and avatar_url fields in the JSON payload. This override does not change the webhook's permanent settings. It only affects the specific message you send.

The override feature is useful when one webhook serves multiple purposes. For example, a single webhook can send alerts from different services, each with its own name and icon. You can also use it to test different display names without creating multiple webhooks. The override works with any programming language or tool that can send HTTP POST requests with a JSON body.

Prerequisites for Using Username Override

Before you can send a webhook message with a custom username, you need:

• A Discord server where you have the Manage Webhooks permission. This is typically available to server moderators and administrators.
• A webhook URL from a text channel in that server. You can create or copy the webhook URL from Server Settings > Integrations > Webhooks.
• A tool or script that can send HTTP POST requests to the webhook URL. Common tools include curl, Python, JavaScript (Node.js), and no-code services like IFTTT or Zapier.

Steps to Send a Webhook Message with a Custom Username

Follow these steps to send a webhook message where the sender name is different from the webhook's default name.

1. Get your webhook URL
   Open Discord and go to your server. Click the server name in the top-left corner, then select Server Settings > Integrations > Webhooks. Find the webhook you want to use and click Copy Webhook URL. Save this URL somewhere secure because anyone with it can send messages to your channel.
2. Prepare your JSON payload
   Create a JSON object that includes the fields you want to send. The basic structure is:
   {
"username": "Your Custom Name",
"content": "Your message text here"
}
   The username field is optional. If you omit it, Discord uses the webhook's default name. The content field holds the message text. You can also add avatar_url to set a custom avatar for this message.
3. Send the POST request
   Use your preferred tool to send an HTTP POST request to the webhook URL. The request must have a Content-Type header set to application/json. The body must be the JSON payload you prepared. Here is an example using curl in a terminal:
   curl -X POST -H "Content-Type: application/json" -d '{"username": "Weather Bot", "content": "Current temperature: 72°F"}' YOUR_WEBHOOK_URL
   Replace YOUR_WEBHOOK_URL with the actual URL you copied.
4. Check the result in Discord
   Go to the text channel where the webhook is set up. You should see a message from the custom username you specified. The message will also show a small “BOT” tag next to the name, indicating it came from a webhook.

Common Mistakes and Limitations When Overriding Usernames

Username Exceeds 80 Characters

Discord limits the custom username to 80 characters. If you send a longer name, Discord ignores the override and uses the webhook's default name. Always check the length of your custom name before sending.

Username Contains Invalid Characters

The username field accepts most Unicode characters, but Discord may strip or ignore certain characters like excessive spaces or special control characters. Stick to standard letters, numbers, spaces, and common symbols.

Avatar URL Fails to Load

If you also set a custom avatar using the avatar_url field, the URL must point to a publicly accessible image file. Discord supports JPG, PNG, and GIF formats. If the image fails to load, Discord shows the webhook's default avatar instead.

Webhook URL is Invalid or Expired

Webhook URLs do not expire, but they can be deleted by a server admin. If you get a 404 error when sending the request, the webhook may have been removed. Create a new webhook and update your script with the new URL.

Discord Webhook Message Fields: JSON Payload vs Default Settings

Feature	Default Webhook Setting	Per-Message Override
Username	Set when creating webhook	Set in username field
Avatar	Set when creating webhook	Set in avatar_url field
Message content	Required in every POST	Set in content field
Embeds	Not available in defaults	Set in embeds array
Rate limit	30 requests per minute	Same limit applies

The per-message override only changes the username and avatar for that single message. The webhook's default name and avatar remain unchanged for future messages that do not include the override fields.

Testing Username Override with a Simple Script

If you want to test the override quickly, you can use a Python script. Python's requests library makes it easy to send HTTP requests. Install the library with pip install requests if you don't have it. Then use this script:

import requests

webhook_url = "YOUR_WEBHOOK_URL"
data = {
    "username": "Test Bot",
    "content": "This is a test message with a custom username."
}

response = requests.post(webhook_url, json=data)
print(response.status_code)

Replace YOUR_WEBHOOK_URL with your actual webhook URL. Run the script. If you see a 204 status code, the message was sent successfully. Check your Discord channel for the message from “Test Bot”.

What to Do If the Username Override Does Not Appear

If your message appears but uses the default webhook name instead of your custom username, check these points:

• Make sure the username field is at the top level of your JSON object. It cannot be nested inside another field.
• Verify that the JSON is valid. Use a JSON validator tool to check for syntax errors like missing commas or quotes.
• Ensure the webhook URL is correct and that you are sending the POST request to the full URL, including the unique ID and token at the end.
• Check that the username does not contain only whitespace or control characters. Discord requires at least one visible character.

You can now send webhook messages with any custom username you choose. This gives you full control over how automated messages appear in your Discord channels. To take it further, try combining the username override with custom avatars and rich embeds for a polished look. Remember that the override only works for messages that include the username field in the JSON payload, so plan your scripts accordingly.