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.

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

Used to represent a webhook.

* These fields will be absent if the webhook creator has since lost access to the guild where the followed channel resides

{
  "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
  }
}

{
  "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
  }
}

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

/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.

An error will be returned if a webhook name (name) is not valid. 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

/channels/{channel.id}/webhooks

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

/guilds/{guild.id}/webhooks

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

/webhooks/{webhook.id}

Returns the new webhook object for the given id.

This request requires the MANAGE_WEBHOOKS permission unless the application making the request owns the webhook. (see: webhook.application_id)

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

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

/webhooks/{webhook.id}

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

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

Same as above, 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.

/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.

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

Same as above, except this call does not require authentication.

/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.

* Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components, and the components field will be ignored unless they set the with_components query param.

** See Uploading Files for details.

*** When the flag 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 response.

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

Refer to Slack's documentation for more information. We do not support Slack's channel, icon_emoji, mrkdwn, or mrkdwn_in properties.

/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 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.

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

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

/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 arrays mentions and mention_roles and the boolean mention_everyone in the message object will be reconstructed from scratch based on the new content. When the message flag IS_COMPONENTS_V2 is set, the reconstructed arrays and boolean are based on the edited content in the components array. 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, that is, without regard to whether or not an allowed_mentions was present in the request that originally created the message.

Refer to Uploading Files for details on attachments and multipart/form-data requests. Any provided files will be appended to the message. To remove or replace files you will have to supply the attachments field which specifies the files to retain on the message after edit.

* The SUPPRESS_EMBEDS flag can be both set and unset, while the IS_COMPONENTS_V2 flag can only be set. When the IS_COMPONENTS_V2 flag is set, any of the used 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 response.

** Application-owned webhooks can always send components. Non-application-owned webhooks cannot send interactive components, and the components field will be ignored unless they set the with_components query param.

*** See Uploading Files for details.

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

/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.