How to Send Discord Webhook Messages With Allowed Mentions Whitelist

When you send messages through a Discord webhook, you can mention @everyone, @here, roles, or individual users. By default, a webhook can mention any of these targets. This can cause unwanted notifications if a webhook is misused or sends a message that tags a large group by mistake. The allowed mentions whitelist lets you restrict which mentions the webhook can actually trigger. This article explains how to configure the allowed_mentions object in your webhook payload so only approved roles or users can be mentioned.

Discord webhooks are powerful tools for integrating external services like GitHub, Jenkins, or custom bots into your server. Without proper controls, a single misconfigured webhook can ping hundreds of members. The allowed_mentions whitelist solves this by letting you define exactly which roles, users, or group mentions (@everyone, @here) the webhook is permitted to use. Any mention not on the whitelist is silently ignored by Discord. This guide covers the JSON structure, practical code examples, and common pitfalls.

What the Allowed Mentions Whitelist Does

The allowed_mentions object is a JSON property you include in the body of a webhook POST request. It controls how Discord handles mentions that appear in the message content. Without this object, a webhook can mention any role, user, or the special @everyone and @here group mentions. With the whitelist, you restrict which mentions actually produce a notification.

The object has three main properties:

parse: An array that can contain the strings “everyone”, “here”, and “roles”. If you include “everyone”, the webhook can mention @everyone. If you include “roles”, the webhook can mention any role by name or ID. To disable all group mentions, set parse to an empty array [].

roles: An array of role IDs (strings) that the webhook is allowed to mention. If you include a role ID here, the webhook can mention that role even if parse does not contain “roles”. If you leave this array empty, no role mentions are allowed unless parse includes “roles”.

users: An array of user IDs (strings) that the webhook is allowed to mention. If you include a user ID here, the webhook can mention that user. If you leave this array empty, no user mentions are allowed unless parse includes “everyone” or “here”.

The whitelist works by priority: the roles and users arrays override the parse array for those specific IDs. For example, if parse is [“everyone”, “here”, “roles”] but the roles array is empty, the webhook can still mention @everyone and @here, but it cannot mention any role. If you want to allow only certain roles and no group mentions, set parse to an empty array and populate the roles array with the specific role IDs.

How to Send a Webhook Message With the Allowed Mentions Whitelist

You send a webhook message by making an HTTP POST request to the webhook URL provided by Discord. The request body must be JSON. Below are the steps for configuring the allowed_mentions object in that JSON payload.

1. Get the webhook URL
   In your Discord server, go to Server Settings > Integrations > Webhooks. Click the webhook you want to use or create a new one. Copy the webhook URL. It looks like https://discord.com/api/webhooks/123456/abcdef.
2. Construct the JSON payload
   Create a JSON object with a content field containing your message. Add an allowed_mentions object as a sibling field. Example:
   { "content": "Hello <@&123456789> and <@987654321>", "allowed_mentions": { "parse": [], "roles": ["123456789"], "users": ["987654321"] } }
   In this example, the role ID 123456789 and user ID 987654321 are whitelisted. The parse array is empty, so @everyone and @here are blocked.
3. Send the POST request
   Use any HTTP client: cURL, Postman, or your programming language of choice. Set the Content-Type header to application/json. Send the JSON payload to the webhook URL. Example cURL command:
   curl -X POST -H "Content-Type: application/json" -d '{"content":"Hello <@&123456789>","allowed_mentions":{"parse":[],"roles":["123456789"]}}' https://discord.com/api/webhooks/123456/abcdef
4. Verify the result
   Check your Discord server. The webhook message should appear. If the mention target is whitelisted, the mention will be highlighted and trigger a notification. If the mention target is not whitelisted, the text will appear as plain text without a notification.

You can also send embeds with webhooks. The allowed_mentions object works the same way — place it at the top level of the JSON, not inside the embed object. Example with an embed:

{
  "embeds": [{
    "title": "Deploy Complete",
    "description": "New version deployed by <@123456789>"
  }],
  "allowed_mentions": {
    "parse": [],
    "users": ["123456789"]
  }
}

Common Mistakes With the Allowed Mentions Whitelist

Mention Still Triggers Notification Even With Empty parse Array

If you set parse to an empty array but the roles or users array contains the target ID, the mention will still work. This is by design — the roles and users arrays override parse for those specific IDs. To completely block all mentions, set parse to an empty array and also set roles and users to empty arrays or omit them entirely.

Using Role Names Instead of Role IDs

The roles array must contain role IDs, not role names. Role IDs are numeric strings. You can get a role ID by enabling Developer Mode in Discord User Settings > Advanced > Developer Mode, then right-clicking the role in Server Settings > Roles and selecting Copy ID. If you use a role name, Discord ignores it and the mention is suppressed.

Forgetting to Include the allowed_mentions Object in Embeds

The allowed_mentions object applies to the entire webhook message, including all embeds. You do not need to repeat it inside each embed. However, if your message contains both content and embeds, the allowed_mentions object must be at the top level. If you place it inside an embed object, Discord ignores it.

Webhook Does Not Have Permission to Mention the Role

Even if you whitelist a role ID, the webhook must have the “Mention @everyone, @here, and All Roles” permission in the channel where the message is sent. This permission is granted by default to webhooks created by administrators. If the webhook lacks this permission, the mention is suppressed regardless of the whitelist.

Configuration	Effect on @everyone	Effect on Role Mentions
No allowed_mentions object	Allowed	Allowed
parse: [“everyone”, “roles”]	Allowed	Allowed
parse: []	Blocked	Blocked
parse: [], roles: [“123”]	Blocked	Only role ID 123 allowed
parse: [“everyone”], roles: []	Allowed	Blocked

The allowed mentions whitelist gives you fine-grained control over webhook notifications. By combining the parse, roles, and users arrays, you can allow only specific roles or users while blocking @everyone and @here. Always test your payload with a small audience before deploying to production channels. Use role IDs instead of names, and verify that the webhook has the necessary permissions in the target channel.