Webhook

Reference for Discord webhook objects and management endpoints.

Webhooks are a low-effort way to post messages to channels in Discord. They do not require a bot user or authentication to use.

Apps can also subscribe to webhook events (i.e. outgoing webhooks) when events happen in Discord, which is detailed in the Webhook Events documentation.

---

Webhook object

Used to represent a webhook.

Webhook structure

id · snowflake · required

The id of the webhook.

type · integer · required

The type of the webhook.

guild_id · ?snowflake

The guild id this webhook is for, if any.

channel_id · ?snowflake · required

The channel id this webhook is for, if any.

user · user object

The user this webhook was created by. Not returned when getting a webhook with its token.

name · ?string · required

The default name of the webhook.

avatar · ?string · required

The default user avatar hash of the webhook.

token · string

The secure token of the webhook. Returned for Incoming Webhooks only.

application_id · ?snowflake · required

The bot/OAuth2 application that created this webhook.

source_guild · partial guild object

The guild of the channel that this webhook is following. Returned for Channel Follower Webhooks. Absent if the webhook creator has since lost access to the guild where the followed channel resides.

source_channel · partial channel object

The channel that this webhook is following. Returned for Channel Follower Webhooks. Absent if the webhook creator has since lost access to the guild where the followed channel resides.

url · string

The url used for executing the webhook. Returned by the webhooks OAuth2 flow.

Webhook types

These types don’t include webhook events, which are outgoing webhooks sent to your app by Discord. See Webhook Events for details.

Value	Name	Description
1	Incoming	Incoming Webhooks can post messages to channels with a generated token
2	Channel Follower	Channel Follower Webhooks are internal webhooks used with Channel Following to post new messages into channels
3	Application	Application webhooks are webhooks used with Interactions

Example incoming webhook

{
  "name": "test webhook",
  "type": 1,
  "channel_id": "199737254929760256",
  "token": "3d89bb7572e0fb30d8128367b3b1b44fecd1726de135cbe28a41f8b2f777c372ba2939e72279b94526ff5d1bd4358d65cf11",
  "avatar": null,
  "guild_id": "199737254929760256",
  "id": "223704706495545344",
  "application_id": null,
  "user": {
    "username": "test",
    "discriminator": "7479",
    "id": "190320984123768832",
    "avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
    "public_flags": 131328
  }
}

Example channel follower webhook

{
  "type": 2,
  "id": "752831914402115456",
  "name": "Guildy name",
  "avatar": "bb71f469c158984e265093a81b3397fb",
  "channel_id": "561885260615255432",
  "guild_id": "56188498421443265",
  "application_id": null,
  "source_guild": {
    "id": "56188498421476534",
    "name": "Guildy name",
    "icon": "bb71f469c158984e265093a81b3397fb"
  },
  "source_channel": {
    "id": "5618852344134324",
    "name": "announcements"
  },
  "user": {
    "username": "test",
    "discriminator": "7479",
    "id": "190320984123768832",
    "avatar": "b004ec1740a63ca06ae2e14c5cee11f3",
    "public_flags": 131328
  }
}

Example application webhook

{
  "type": 3,
  "id": "658822586720976555",
  "name": "Clyde",
  "avatar": "689161dc90ac261d00f1608694ac6bfd",
  "channel_id": null,
  "guild_id": null,
  "application_id": "658822586720976555"
}

---

Create webhook

POST /channels/{channel.id}/webhooks

Creates a new webhook and returns a webhook object on success. Requires the MANAGE_WEBHOOKS permission. Fires a Webhooks Update Gateway event.

A webhook name is valid if:

• It does not contain the substrings clyde or discord (case-insensitive)
• It follows the nickname guidelines in the Usernames and Nicknames documentation, with an exception that webhook names can be up to 80 characters

This endpoint supports the X-Audit-Log-Reason header.

JSON params

name · string · required

Name of the webhook (1–80 characters).

avatar · ?image data

Image for the default webhook avatar. See image data.

Get channel webhooks

GET /channels/{channel.id}/webhooks

Returns a list of channel webhook objects. Requires the MANAGE_WEBHOOKS permission.

Get guild webhooks

GET /guilds/{guild.id}/webhooks

Returns a list of guild webhook objects. Requires the MANAGE_WEBHOOKS permission.

Get webhook

GET /webhooks/{webhook.id}

Returns the webhook object for the given id.

This request requires the MANAGE_WEBHOOKS permission unless the application making the request owns the webhook.

Get webhook with token

GET /webhooks/{webhook.id}/{webhook.token}

Same as Get webhook, except this call does not require authentication and returns no user in the webhook object.

Modify webhook

PATCH /webhooks/{webhook.id}

Modify a webhook. Requires the MANAGE_WEBHOOKS permission. Returns the updated webhook object on success. Fires a Webhooks Update Gateway event.

All parameters to this endpoint are optional.

This endpoint supports the X-Audit-Log-Reason header.

JSON params

name · string

The default name of the webhook.

avatar · ?image data

Image for the default webhook avatar. See image data.

channel_id · snowflake

The new channel id this webhook should be moved to.

Modify webhook with token

PATCH /webhooks/{webhook.id}/{webhook.token}

Same as Modify webhook, except this call does not require authentication, does not accept a channel_id parameter in the body, and does not return a user in the webhook object.

Delete webhook

DELETE /webhooks/{webhook.id}

Delete a webhook permanently. Requires the MANAGE_WEBHOOKS permission. Returns a 204 No Content response on success. Fires a Webhooks Update Gateway event.

This endpoint supports the X-Audit-Log-Reason header.

Delete webhook with token

DELETE /webhooks/{webhook.id}/{webhook.token}

Same as Delete webhook, except this call does not require authentication.

Execute webhook

POST /webhooks/{webhook.id}/{webhook.token}

Refer to Uploading Files for details on attachments and multipart/form-data requests. Returns a message or 204 No Content depending on the wait query parameter.

When sending a message, you must provide a value for at least one of content, embeds, components, file, or poll.

If the webhook channel is a forum or media channel, you must provide either thread_id in the query string params or thread_name in the JSON/form params. If thread_id is provided, the message will send in that thread. If thread_name is provided, a thread with that name will be created in the channel.

Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using allowed_mentions to prevent unexpected mentions.

Query string params

wait · boolean · default: "false"

Waits for server confirmation of message send before responding. When false, a message that is not saved does not return an error.

thread_id · snowflake

Send a message to the specified thread within a webhook’s channel. The thread will automatically be unarchived.

with_components · boolean · default: "false"

Whether to respect the components field of the request. When enabled, allows application-owned webhooks to use all components and non-owned webhooks to use non-interactive components.

JSON/form params

content · string

The message contents (up to 2000 characters). Required if file, embeds, and poll are not provided.

username · string

Override the default username of the webhook.

avatar_url · string

Override the default avatar of the webhook.

tts · boolean

true if this is a TTS message.

embeds · array of embed objects

Embedded rich content (up to 10 embeds). Required if content, file, and poll are not provided.

allowed_mentions · allowed mention object

Allowed mentions for the message.

components · array of message component objects

The components to include with the message. Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components unless with_components is set.

files[n] · file contents

The contents of the file being sent. Required if content, embeds, and poll are not provided. See Uploading Files for details.

payload_json · string

JSON encoded body of non-file params. Only for multipart/form-data requests.

attachments · array of partial attachment objects

Attachment objects with filename and description. See Uploading Files for details.

flags · integer

Message flags combined as a bitfield. Only SUPPRESS_EMBEDS, SUPPRESS_NOTIFICATIONS, and IS_COMPONENTS_V2 can be set. When IS_COMPONENTS_V2 is set, the webhook message can only contain components — providing content, embeds, files[n], or poll will fail with a 400 BAD REQUEST.

thread_name · string

Name of thread to create. Requires the webhook channel to be a forum or media channel.

applied_tags · array of snowflakes

Array of tag ids to apply to the thread. Requires the webhook channel to be a forum or media channel.

poll · poll request object

A poll. Required if content, file, and embeds are not provided. See poll create request object.

For webhook embed objects, you can set every field except type (it will be rich regardless), provider, video, and any height, width, or proxy_url values for images.

Execute Slack-compatible webhook

POST /webhooks/{webhook.id}/{webhook.token}/slack

Refer to Slack’s documentation for more information. Discord does not support Slack’s channel, icon_emoji, mrkdwn, or mrkdwn_in properties.

Query string params

thread_id · snowflake

Id of the thread to send the message in.

wait · boolean · default: "true"

Waits for server confirmation of message send before responding. When false, a message that is not saved does not return an error.

Execute GitHub-compatible webhook

POST /webhooks/{webhook.id}/{webhook.token}/github

Add a new webhook to your GitHub repo (in the repo’s settings) and use this endpoint as the “Payload URL.” You can choose what events your Discord channel receives by selecting “Let me select individual events” when configuring the webhook.

The supported GitHub events are: commit_comment, create, delete, fork, issue_comment, issues, member, public, pull_request, pull_request_review, pull_request_review_comment, push, release, watch, check_run, check_suite, discussion, and discussion_comment.

Query string params

thread_id · snowflake

Id of the thread to send the message in.

wait · boolean · default: "true"

Waits for server confirmation of message send before responding. When false, a message that is not saved does not return an error.

Get webhook message

GET /webhooks/{webhook.id}/{webhook.token}/messages/{message.id}

Returns a previously-sent webhook message from the same token. Returns a message object on success.

Query string params

thread_id · snowflake

Id of the thread the message is in.

Edit webhook message

PATCH /webhooks/{webhook.id}/{webhook.token}/messages/{message.id}

Edits a previously-sent webhook message from the same token. Returns a message object on success.

When the content field is edited, the mentions, mention_roles, and mention_everyone fields in the message object will be reconstructed from scratch based on the new content. The allowed_mentions field of the edit request controls how this happens. If there is no explicit allowed_mentions in the edit request, the content will be parsed with default allowances, without regard to whether or not an allowed_mentions was present in the original request.

Any provided files will be appended to the message. To remove or replace files you will need to supply the attachments field, which specifies the files to retain on the message after edit.

Starting with API v10, the attachments array must contain all attachments that should be present after edit, including retained and new attachments provided in the request body.

All parameters to this endpoint are optional and nullable.

Query string params

thread_id · snowflake

Id of the thread the message is in.

with_components · boolean · default: "false"

Whether to respect the components field of the request. When enabled, allows application-owned webhooks to use all components and non-owned webhooks to use non-interactive components.

JSON/form params

content · string

The message contents (up to 2000 characters).

embeds · array of embed objects

Embedded rich content (up to 10 embeds).

flags · integer

Message flags combined as a bitfield. Only SUPPRESS_EMBEDS and IS_COMPONENTS_V2 can be set. SUPPRESS_EMBEDS can be both set and unset, while IS_COMPONENTS_V2 can only be set. When IS_COMPONENTS_V2 is set, any content, embeds, files[n], or poll values in the initial message must be set to null first, otherwise it will fail with a 400 BAD REQUEST.

allowed_mentions · allowed mention object

Allowed mentions for the message.

components · array of message component objects

The components to include with the message. Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components unless with_components is set.

files[n] · file contents

The contents of the file being sent/edited. See Uploading Files for details.

payload_json · string

JSON encoded body of non-file params. Only for multipart/form-data requests.

attachments · array of partial attachment objects

Attached files to keep and possible descriptions for new files. See Uploading Files for details.

poll · poll request object

A poll. Polls can only be added when editing a deferred interaction response.

Delete webhook message

DELETE /webhooks/{webhook.id}/{webhook.token}/messages/{message.id}

Deletes a message that was created by the webhook. Returns a 204 No Content response on success.

Query string params

thread_id · snowflake

Id of the thread the message is in.