Webhooks
Webhooks are a low-effort way to post messages to channels in Discord. They do not require a bot user or authentication to use.
Used to represent a webhook.
id
snowflake
The ID of the webhook
guild_id?
?snowflake
The guild ID this webhook is for, if any
channel_id
?snowflake
The channel ID this webhook is for, if any
name
?string
The default name of the webhook (1-80 characters)
token? 1
string
The secure token of the webhook (returned for INCOMING webhooks)
application_id
?snowflake
The application that created this webhook
source_guild? 2
integration guild object
The guild of the channel that this webhook is following (returned for CHANNEL_FOLLOWER webhooks)
source_channel? 2
webhook channel object
The channel that this webhook is following (returned for CHANNEL_FOLLOWER webhooks)
url? 1
string
The URL used for executing the webhook (returned for INCOMING webhooks)
1 For application-owned webhooks, this field is only returned to the application that created the webhook.
2 These fields will not be included if the webhook creator has since lost access to the followed channel's guild.
1
INCOMING
Incoming webhooks can post messages to channels with a generated token
2
CHANNEL_FOLLOWER
Channel Follower webhooks are internal webhooks used to post new messages into channels
3
APPLICATION
Application webhooks are webhooks used with interactions
id
snowflake
The ID of the channel
name
string
The name of the channel (1-100 characters)
{ "application_id": null, "avatar": null, "channel_id": "199737254929760256", "guild_id": "199737254929760256", "id": "223704706495545344", "name": "test webhook", "type": 1, "user": { "id": "828387742575624222", "username": "jupppper", "avatar": "e14a7c62b0b38068be88be194b23910f", "discriminator": "0", "public_flags": 16384, "banner": null, "accent_color": null, "global_name": "Jup", "avatar_decoration_data": null, "primary_guild": null }, "token": "3d89bb7572e0fb30d8128367b3b1b44fecd1726de135cbe28a41f8b2f777c372ba2939e72279b94526ff5d1bd4358d65cf11", "url": "https://discord.com/api/webhooks/223704706495545344/3d89bb7572e0fb30d8128367b3b1b44fecd1726de135cbe28a41f8b2f777c372ba2939e72279b94526ff5d1bd4358d65cf11"}Example Channel Follower Webhook
{ "application_id": null, "avatar": "bb71f469c158984e265093a81b3397fb", "channel_id": "561885260615255432", "guild_id": "56188498421443265", "id": "752831914402115456", "name": "Guildy name", "type": 2, "source_guild": { "id": "56188498421476534", "name": "Guildy name", "icon": "bb71f469c158984e265093a81b3397fb" }, "source_channel": { "id": "5618852344134324", "name": "announcements" }, "user": { "id": "828387742575624222", "username": "jupppper", "avatar": "e14a7c62b0b38068be88be194b23910f", "discriminator": "0", "public_flags": 16384, "banner": null, "accent_color": null, "global_name": "Jup", "avatar_decoration_data": null, "primary_guild": null }}{ "application_id": "658822586720976555", "avatar": "689161dc90ac261d00f1608694ac6bfd", "channel_id": null, "guild_id": null, "id": "658822586720976555", "name": "Clyde", "type": 3, "user": null}POST/channels/{channel.id}/webhooks
Creates a new webhook. Requires the permission. Returns a webhook object on success. Fires a Webhooks Update Gateway event.
name
string
The default name of the webhook (1-80 characters)
GET/channels/{channel.id}/webhooks
Returns a list of channel webhook objects. Requires the permission.
GET/guilds/{guild.id}/webhooks
Returns a list of guild webhook objects. Requires the permission.
GET/webhooks/{webhook.id}
Returns a webhook object for the given webhook ID. Requires the permission unless the application making the request owns the webhook.
GET/webhooks/{webhook.id}/{webhook.token}
Same as above, except this call does not require authentication.
PATCH/webhooks/{webhook.id}
Modifies a webhook. Requires the permission. Returns the updated webhook object on success. Fires a Webhooks Update Gateway event.
name?
string
The default name of the webhook (1-80 characters)
channel_id?
snowflake
The channel ID this webhook should be moved to
PATCH/webhooks/{webhook.id}/{webhook.token}
Same as above, except this call does not require authentication and does not accept a parameter.
name?
string
The default name of the webhook (1-80 characters)
DELETE/webhooks/{webhook.id}
Deletes a webhook permanently. Requires the permission. Returns a 204 empty response on success. Fires a Webhooks Update Gateway event.
DELETE/webhooks/{webhook.id}/{webhook.token}
Same as above, except this call does not require authentication.
POST/webhooks/{webhook.id}/{webhook.token}
Posts a message to the webhook's channel. Returns a message object or 204 empty response, depending on . Fires a Message Create Gateway event. See message formatting for more information on how to properly format messages.
Files must be attached using a body (or pre-uploaded to Discord's GCP bucket) as described in Uploading Files.
When executing on a forum channel, one of or must be provided.
The maximum request size when sending a message is 100 MiB.
For the embed object, you can set every field except (it will be regardless of if you try to set it), , , and any , , or values for images.
wait?
boolean
Waits for confirmation of message send before response, and returns the created message body (default false; 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
username?
string
The name to override the default username of the webhook with (1-80 characters)
avatar_url?
string
The avatar URL to override the default avatar of the webhook with
thread_name?
string
The name for the thread to create (requires the webhook channel to be a thread-only channel, 1-100 characters)
applied_tags?
array[snowflake]
The IDs of the tags that are applied to the thread (requires the webhook channel to be a thread-only channel, max 5)
content?
string
The message contents (up to 2000 characters)
tts?
boolean
Whether this is a TTS message
flags?
integer
The message's flags (only SUPPRESS_EMBEDS, SUPPRESS_NOTIFICATIONS, and VOICE_MESSAGE can be set)
files[n]? 1
file contents
Contents of the file being sent (max 10)
payload_json? 1
string
JSON-encoded body of non-file params
attachments? 1
array[partial attachment object]
Partial attachment objects with filename and description (max 10)
1 See Uploading Files for details.
2 Requires query parameter. Interactions only work with an application-owned webhook.
POST/webhooks/{webhook.id}/{webhook.token}/slack
Refer to Slack's documentation for more information. We do not support Slack's , , , or properties.
wait?
boolean
Waits for confirmation of message send before response, and returns the created message body (default false; 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
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 choosing the "Let me select individual events" option and selecting individual events for the new webhook you're configuring. The supported events are , , , , , , , , , , , , , , , , , and .
wait?
boolean
Waits for confirmation of message send before response, and returns the created message body (default false; 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
GET/webhooks/{webhook.id}/{webhook.token}/messages/{message.id}
Returns a previously-sent webhook message object from the same token.
PATCH/webhooks/{webhook.id}/{webhook.token}/messages/{message.id}
Edits a previously-sent webhook message from the same token. Returns the updated message object on success. Fires a Message Update Gateway event.
When the field is edited, the array in the message object will be reconstructed from scratch based on the new content. The field of the edit request controls how this happens. If there is no explicit in the edit request, the content will be parsed with default allowances, that is, without regard to whether or not an was present in the request that originally created the message.
Refer to Uploading Files for details on attachments and requests. Any provided files will be appended to the message. To remove or replace files you will have to supply the field which specifies the files to retain on the message after edit.
content?
string
The message contents (up to 2000 characters)
tts?
boolean
Whether this is a TTS message
flags?
integer
The message's flags (only SUPPRESS_EMBEDS, SUPPRESS_NOTIFICATIONS, and VOICE_MESSAGE can be set)
files[n]? 1
file contents
Contents of the file being sent (max 10)
payload_json? 1
string
JSON-encoded body of non-file params
attachments? 1
array[partial attachment object]
Partial attachment objects with filename and description (max 10)
1 See Uploading Files for details.
2 Requires an application-owned webhook.
DELETE/webhooks/{webhook.id}/{webhook.token}/messages/{message.id}
Deletes a message that was created by the webhook. Returns a 204 empty response on success. Fires a Message Delete Gateway event.