Webhook Resource

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

Webhook Object

Used to represent a webhook.
Webhook Structure
FieldTypeDescription
idsnowflakethe id of the webhook
guild_idsnowflake?the guild id this webhook is for
channel_idsnowflakethe channel id this webhook is for
userUser?the user this webhook was created by (not returned when getting a webhook with its token)
name?stringthe default name of the webhook
avatar?stringthe default avatar of the webhook
tokenstringthe secure token of the webhook
Webhook Example
{
    "name": "test webhook",
    "channel_id": "199737254929760256",
    "token": "3d89bb7572e0fb30d8128367b3b1b44fecd1726de135cbe28a41f8b2f777c372ba2939e72279b94526ff5d1bd4358d65cf11",
    "avatar": null,
    "guild_id": "199737254929760256",
    "id": "223704706495545344",
    "user": {
        "username": "test",
        "discriminator": "7479",
        "id": "190320984123768832",
        "avatar": "b004ec1740a63ca06ae2e14c5cee11f3"
    }
}

Create Webhook

POST/channels/{channel.id}/webhooks
Create a new webhook. Returns a webhook object on success.
JSON Params
FieldTypeDescription
namestringname of the webhook (2-100 characters)
avataravatar database64 128x128 jpeg image for the default webhook avatar

Get Channel Webhooks

GET/channels/{channel.id}/webhooks
Returns a list of channel webhook objects.

Get Guild Webhooks

GET/guilds/{guild.id}/webhooks
Returns a list of guild webhook objects.

Get Webhook

GET/webhooks/{webhook.id}
Returns the new webhook object for the given id.

Get Webhook with Token

GET/webhooks/{webhook.id}/{webhook.token}
Same as above, except this call does not require authentication and returns no user in the webhook object.

Modify Webhook

PATCH/webhooks/{webhook.id}
Modify a webhook. Returns the updated webhook object on success.
All parameters to this endpoint are optional
JSON Params
FieldTypeDescription
namestringthe default name of the webhook
avataravatar database64 128x128 jpeg image for the default webhook avatar

Modify Webhook with Token

PATCH/webhooks/{webhook.id}/{webhook.token}
Same as above, except this call does not require authentication and returns no user in the webhook object.

Delete Webhook

DELETE/webhooks/{webhook.id}
Delete a webhook permanently. User must be owner. Returns a 204 NO CONTENT response on success.

Delete Webhook with Token

DELETE/webhooks/{webhook.id}/{webhook.token}
Same as above, except this call does not require authentication.

Execute Webhook

POST/webhooks/{webhook.id}/{webhook.token}
This endpoint supports both JSON and form data bodies. It does require multipart/form-data requests instead of the normal JSON request type when uploading files. Make sure you set your Content-Type to multipart/form-data if you're doing that. Note that in that case, the embeds field cannot be used, but you can pass an url-encoded JSON body as a form value for payload_json.
Querystring Params
FieldTypeDescriptionRequired
waitboolwaits for server confirmation of message send before response, and returns the created message body (defaults to false; when false a message that is not saved does not return an error)false
JSON/Form Params
FieldTypeDescriptionRequired
contentstringthe message contents (up to 2000 characters)one of content, file, embeds
usernamestringoverride the default username of the webhookfalse
avatar_urlstringoverride the default avatar of the webhookfalse
ttsbooltrue if this is a TTS messagefalse
filefile contentsthe contents of the file being sentone of content, file, embeds
embedsarray of embed objectsembedded rich contentone of content, file, embeds
For the webhook embed objects, you can set every field except type (it will be rich regardless of if you try to set it), provider, video, and any height, width, or proxy_url values for images.

Execute Slack-Compatible Webhook

POST/webhooks/{webhook.id}/{webhook.token}/slack
Querystring Params
FieldTypeDescriptionRequired
waitboolwaits for server confirmation of message send before response (defaults to true; when false a message that is not saved does not return an error)false
Refer to Slack's documentation for more information. We do not support Slack's channel, icon_emoji, mrkdwn, or mrkdwn_in properties.

Execute GitHub-Compatible Webhook

POST/webhooks/{webhook.id}/{webhook.token}/github
Querystring Params
FieldTypeDescriptionRequired
waitboolwaits for server confirmation of message send before response (defaults to true; when false a message that is not saved does not return an error)false
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.