Add Webhook Events documentation (#7233)

* outline webhook and event docs * application authorized * receiving events * add webhook event config * move preparing * connecting dots * fix broken links * add webhook types * cleanup * quest user enrollment * some reorganizing * smul edits * add descriptions on application page * add callout * oop * yoni edits + entitlement create example * update table column name * oops * update wording * fixy * real fixy * cleanup * small edits * change log * oops * tables * Update docs/events/Webhook_Events.mdx Co-authored-by: Suspense <[email protected]> --------- Co-authored-by: Suspense <[email protected]>
discord · Oct 25, 2024 · 2e6be43 · 2e6be43
1 parent cfd45f7
commit 2e6be43
Show file tree

Hide file tree

Showing 65 changed files with 773 additions and 465 deletions.
diff --git a/docs/Reference.mdx b/docs/Reference.mdx
@@ -126,7 +126,7 @@ All HTTP-layer services and protocols (e.g. HTTP, WebSocket) within the Discord
 
 ## Snowflakes
 
-Discord utilizes Twitter's [snowflake](https://github.com/twitter-archive/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/encoding-and-compression) for more information regarding Gateway encoding.
+Discord utilizes Twitter's [snowflake](https://github.com/twitter-archive/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_EVENTS_GATEWAY/encoding-and-compression) for more information regarding Gateway encoding.
 
 ###### Snowflake ID Broken Down in Binary
 
@@ -245,7 +245,7 @@ Certain endpoints in the API are documented to accept booleans for their query s
 
 ## Gateway (WebSocket) API
 
-Discord's Gateway API is used for maintaining persistent, stateful websocket connections between your client and our servers. These connections are used for sending and receiving real-time events your client can use to track and update local state. The Gateway API uses secure websocket connections as specified in [RFC 6455](https://tools.ietf.org/html/rfc6455). For information on opening Gateway connections, please see the [Gateway API](#DOCS_TOPICS_GATEWAY/connections) section.
+Discord's Gateway API is used for maintaining persistent, stateful websocket connections between your client and our servers. These connections are used for sending and receiving real-time events your client can use to track and update local state. The Gateway API uses secure websocket connections as specified in [RFC 6455](https://tools.ietf.org/html/rfc6455). For information on opening Gateway connections, please see the [Gateway API](#DOCS_EVENTS_GATEWAY/connections) section.
 
 ## Message Formatting
 
@@ -337,7 +337,7 @@ Discord uses ids and hashes to render images in the client. These hashes can be
 | Avatar Decoration           | avatar-decoration-presets/[avatar_decoration_data_asset](#DOCS_RESOURCES_USER/avatar-decoration-data-object).png                                                                                                                                                                                                                                                              | PNG                  |
 | Application Icon            | app-icons/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[icon](#DOCS_RESOURCES_APPLICATION/application-object).png                                                                                                                                                                                                                                         | PNG, JPEG, WebP      |
 | Application Cover           | app-icons/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[cover_image](#DOCS_RESOURCES_APPLICATION/application-object).png                                                                                                                                                                                                                                  | PNG, JPEG, WebP      |
-| Application Asset           | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[asset_id](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-assets).png                                                                                                                                                                                                                       | PNG, JPEG, WebP      |
+| Application Asset           | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[asset_id](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-assets).png                                                                                                                                                                                                                       | PNG, JPEG, WebP      |
 | Achievement Icon            | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/achievements/[achievement_id](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct)/icons/[icon_hash](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct).png | PNG, JPEG, WebP      |
 | Store Page Asset            | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/store/asset_id                                                                                                                                                                                                                                                                                    | PNG, JPEG, WebP      |
 | Sticker Pack Banner         | app-assets/710982414301790216/store/[sticker_pack_banner_asset_id](#DOCS_RESOURCES_STICKER/sticker-pack-object).png                                                                                                                                                                                                                                                           | PNG, JPEG, WebP      |

diff --git a/docs/change_log/2017-07-19-breaking-change-version-6.md b/docs/change_log/2017-07-19-breaking-change-version-6.md
@@ -10,5 +10,5 @@ breaking: true
   * `recipient` is now `recipients`, an array of [user](#DOCS_RESOURCES_USER/user-object) objects
 * [Message](#DOCS_RESOURCES_MESSAGE/message-object) Object
   * [`type`](#DOCS_RESOURCES_MESSAGE/message-object-message-types) added to support system messages
-* [Status Update](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence-gateway-presence-update-structure) Object
+* [Status Update](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence-gateway-presence-update-structure) Object
   * `idle_since` renamed to `since`
diff --git a/docs/change_log/2017-08-16-breaking-change-presence-activity-objects.md b/docs/change_log/2017-08-16-breaking-change-presence-activity-objects.md
@@ -4,4 +4,4 @@ date: "2017-08-16"
 breaking: true
 ---
 
-The `type` field in the [activity object](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object) for [Gateway Status Update](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence) and [Presence Update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) payloads is no longer optional when the activity object is not null.
+The `type` field in the [activity object](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object) for [Gateway Status Update](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence) and [Presence Update](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update) payloads is no longer optional when the activity object is not null.
diff --git a/docs/change_log/2018-01-03-semi-breaking-change-very-large-bot-sharding.md b/docs/change_log/2018-01-03-semi-breaking-change-very-large-bot-sharding.md
@@ -4,4 +4,4 @@ date: "2018-01-03"
 breaking: true
 ---
 
-Additional sharding requirements and information for bots in over 100,000 guilds has been added. This requires a small change in numbers of shards for affected bots. See the [documentation](#DOCS_TOPICS_GATEWAY/sharding-for-large-bots) for more information.
+Additional sharding requirements and information for bots in over 100,000 guilds has been added. This requires a small change in numbers of shards for affected bots. See the [documentation](#DOCS_EVENTS_GATEWAY/sharding-for-large-bots) for more information.
diff --git a/...change_log/2018-06-19-documentation-fix-list-of-open-dms-in-certain-payloads.md b/...change_log/2018-06-19-documentation-fix-list-of-open-dms-in-certain-payloads.md
@@ -3,4 +3,4 @@ title: "Documentation Fix: List of Open DMS in Certain Payloads"
 date: "2018-06-19"
 ---
 
-The documentation has been updated to correctly note that the `private_channels` field in the [Ready](#DOCS_TOPICS_GATEWAY_EVENTS/ready) should be an empty array, as well as the response from `/users/@me/channels` for a bot user. This change has been in effect for a long time, but the documentation was not updated.
+The documentation has been updated to correctly note that the `private_channels` field in the [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) should be an empty array, as well as the response from `/users/@me/channels` for a bot user. This change has been in effect for a long time, but the documentation was not updated.
diff --git a/docs/change_log/2020-02-14-gateway-intents.md b/docs/change_log/2020-02-14-gateway-intents.md
@@ -3,14 +3,14 @@ title: "Gateway Intents"
 date: "2020-02-14"
 ---
 
-We've added documentation around a brand new feature: [Gateway Intents!](#DOCS_TOPICS_GATEWAY/gateway-intents) Gateway Intents are a great way to specify which events you want to receive from our gateway. Go on, save yourself some bandwidth and CPU usage.
+We've added documentation around a brand new feature: [Gateway Intents!](#DOCS_EVENTS_GATEWAY/gateway-intents) Gateway Intents are a great way to specify which events you want to receive from our gateway. Go on, save yourself some bandwidth and CPU usage.
 
 Using Intents will change the behavior of some existing events and commands, so please refer to:
 
-* [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create)
-* [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members)
-* [Guild Member Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-add)
-* [Guild Member Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-remove)
-* [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update)
-* [Presence Update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update)
+* [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create)
+* [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members)
+* [Guild Member Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-add)
+* [Guild Member Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-remove)
+* [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update)
+* [Presence Update](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update)
 * [List Guild Members](#DOCS_RESOURCES_GUILD/list-guild-members)
diff --git a/docs/change_log/2020-03-02-new-invite-events-and-reactions-endpoint.md b/docs/change_log/2020-03-02-new-invite-events-and-reactions-endpoint.md
@@ -6,6 +6,6 @@ date: "2020-03-02"
 We've added a new endpoint for deleting all reactions of a specific emoji from a message, as well as some new invite and reaction gateway events. Read more:
 
 * [Delete All Reactions for Emoji](#DOCS_RESOURCES_MESSAGE/delete-all-reactions-for-emoji)
-* [Invite Create](#DOCS_TOPICS_GATEWAY_EVENTS/invite-create)
-* [Invite Delete](#DOCS_TOPICS_GATEWAY_EVENTS/invite-delete)
-* [Message Reaction Remove Emoji](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove-emoji)
+* [Invite Create](#DOCS_EVENTS_GATEWAY_EVENTS/invite-create)
+* [Invite Delete](#DOCS_EVENTS_GATEWAY_EVENTS/invite-delete)
+* [Message Reaction Remove Emoji](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove-emoji)
diff --git a/docs/change_log/2020-04-24-new-properties-on-guild-members-chunk-event.md b/docs/change_log/2020-04-24-new-properties-on-guild-members-chunk-event.md
@@ -3,4 +3,4 @@ title: "New Properties on Guild Members Chunk Event"
 date: "2020-04-24"
 ---
 
-The [Guild Members Chunk](#DOCS_TOPICS_GATEWAY_EVENTS/guild-members-chunk) gateway event now contains two properties: `chunk_index` and `chunk_count`. These values can be used to keep track of how many events you have left to receive in response to a [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) command.
+The [Guild Members Chunk](#DOCS_EVENTS_GATEWAY_EVENTS/guild-members-chunk) gateway event now contains two properties: `chunk_index` and `chunk_count`. These values can be used to keep track of how many events you have left to receive in response to a [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) command.
diff --git a/docs/change_log/2020-09-24-api-and-gateway-v8.md b/docs/change_log/2020-09-24-api-and-gateway-v8.md
@@ -8,18 +8,18 @@ We've introduced API and Gateway v8! Changes are noted throughout the documentat
 The changes are:
 
 * API and Gateway v8 are now available. v6 is still the default for the time being.
-* [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents) are now required
-* Removed `guild_subscriptions` in identify in favor of [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents).
+* [Gateway Intents](#DOCS_EVENTS_GATEWAY/gateway-intents) are now required
+* Removed `guild_subscriptions` in identify in favor of [Gateway Intents](#DOCS_EVENTS_GATEWAY/gateway-intents).
 * All permissions have been converted to strings-serialized numbers. As such, `permissions_new`, `allow_new`, and `deny_new` have been removed
 * The `game` field has been removed. If you need a direct replacement, you can instead reference the first element of `activities`
 * Channel Permission Overwrite `type`s are now numbers (0 and 1) instead of strings ("role" and "member"). However due to a current technical constraint, they are string-serialized numbers in audit log `options`.
 * `embed_enabled` and `embed_channel_id` have been removed. Use `widget_enabled` and `widget_channel_id` instead.
 * Form body errors have been improved to include more helpful messaging on validation. [See more here](#DOCS_REFERENCE/error-messages)
 * The `Retry-After` header value and `retry_after` body value is now based in seconds instead of milliseconds (e.g. `123` means 123 seconds)
 * The `X-RateLimit-Precision` header is no longer respected. `X-RateLimit-Reset` and `X-RateLimit-Reset-After` are always returned at millisecond precision (e.g. `123.456` instead of `124`)
-* Bots no longer receive [Channel Create Gateway Event](#DOCS_TOPICS_GATEWAY_EVENTS/channel-create) for DMs
+* Bots no longer receive [Channel Create Gateway Event](#DOCS_EVENTS_GATEWAY_EVENTS/channel-create) for DMs
 * `delete-message-days` is no longer available. Use `delete_message_days`.
-* Removed `roles`, `premium_since`, and `nick` from [Presence Update Gateway Event](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update)
+* Removed `roles`, `premium_since`, and `nick` from [Presence Update Gateway Event](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update)
 * Removed some [integration object](#DOCS_RESOURCES_GUILD/integration-object) fields for Discord application integrations
 * Removed `include_applications` from [Get Guild Integrations](#DOCS_RESOURCES_GUILD/get-guild-integrations). Application integrations are always included.
 * The following deprecated routes have been removed for better naming conventions:

diff --git a/docs/change_log/2020-10-27-gateway-v6-intent-restrictions.md b/docs/change_log/2020-10-27-gateway-v6-intent-restrictions.md
@@ -3,7 +3,7 @@ title: "Gateway v6 Intent Restrictions"
 date: "2020-10-27"
 ---
 
-The v6 gateway now applies the restrictions for gateway intents. This means the new chunking limitations are now in effect, regardless of intents being used. See [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) for further details.
+The v6 gateway now applies the restrictions for gateway intents. This means the new chunking limitations are now in effect, regardless of intents being used. See [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) for further details.
 Additionally, if privileged intents are not enabled in the application dashboard the bot will not receive the events for those intents.
 
 All other intents are always enabled by default unless specified otherwise by the identify payload. We have made a support article to explain some of the changes and resulting issues with more details: [Gateway Update FAQ](https://dis.gd/gwupdate)
diff --git a/docs/change_log/2020-11-16-inline-replies.md b/docs/change_log/2020-11-16-inline-replies.md
@@ -9,4 +9,4 @@ Inline Replies have been added to our documentation. They behave differently in
 * You can now add a `message_reference` on message create to create a reply
 * A new field `referenced_message` has been added to the [Message Object](#DOCS_RESOURCES_MESSAGE/message-object)
 * A new field `replied_user` has been added to the [Allowed Mentions Object](#DOCS_RESOURCES_MESSAGE/allowed-mentions-object)
-* [Message Create](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) gateway event is guaranteed to have a `referenced_message` if the message created is a reply. Otherwise, that field is not guaranteed.
+* [Message Create](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) gateway event is guaranteed to have a `referenced_message` if the message created is a reply. Otherwise, that field is not guaranteed.
diff --git a/docs/change_log/2022-02-14-api-v10.md b/docs/change_log/2022-02-14-api-v10.md
@@ -5,7 +5,7 @@ date: "2022-02-14"
 
 * API v8 is now deprecated.
 * `GET /channels/{channel.id}/threads/active` is decommissioned in favor of [`GET /guilds/{guild.id}/threads/active`](#DOCS_RESOURCES_GUILD/list-active-guild-threads).
-* Starting in v10, you must specify the message content intent (`1 << 15`) to receive content-related fields in message dispatches. Read more in the [Gateway Intents documentation](#DOCS_TOPICS_GATEWAY/gateway-intents).
+* Starting in v10, you must specify the message content intent (`1 << 15`) to receive content-related fields in message dispatches. Read more in the [Gateway Intents documentation](#DOCS_EVENTS_GATEWAY/gateway-intents).
 * To specify a reason for an administrative action in audit logs, apps must now pass the `X-Audit-Log-Reason` header rather than the `reason` parameter for all endpoints. Read more in the [Audit Logs documentation](#DOCS_RESOURCES_AUDIT_LOG).
 * Message routes (like [`POST /channels/{channel.id}/messages`](#DOCS_RESOURCES_MESSAGE/create-message)) now use the `embeds` field (an array of embed objects) instead of `embed`.
 * The `summary` field for [applications](#DOCS_RESOURCES_APPLICATION) now returns an empty string for all API versions.

diff --git a/docs/change_log/2022-04-27-updated-command-permissions.md b/docs/change_log/2022-04-27-updated-command-permissions.md
@@ -19,4 +19,4 @@ Application command permissions have been updated to add more granular control a
 * [constant (`guild_id - 1`)](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-permissions-object-application-command-permissions-constants) to represent all channels in command permissions
 * Added `default_member_permissions` field, which is a bitwise OR-ed set of [permissions](#DOCS_TOPICS_PERMISSIONS/permissions-bitwise-permission-flags), expressed as a string. This replaces the `default_permission` field, which will soon be deprecated.
 * Added `dm_permission`, which is a boolean flag used to indicate whether a command is available in DMs (only for global application commands). If no value is passed, the global command will be visible in DMs.
-* Added `APPLICATION_COMMAND_PERMISSIONS_UPDATE` [gateway](#DOCS_TOPICS_GATEWAY_EVENTS/application-command-permissions-update) event and `APPLICATION_COMMAND_PERMISSION_UPDATE` [audit log](#DOCS_RESOURCES_AUDIT_LOG) event.
+* Added `APPLICATION_COMMAND_PERMISSIONS_UPDATE` [gateway](#DOCS_EVENTS_GATEWAY_EVENTS/application-command-permissions-update) event and `APPLICATION_COMMAND_PERMISSION_UPDATE` [audit log](#DOCS_RESOURCES_AUDIT_LOG) event.
diff --git a/docs/change_log/2022-06-16-auto-moderation.md b/docs/change_log/2022-06-16-auto-moderation.md
@@ -6,6 +6,6 @@ date: "2022-06-16"
 Add new [Auto Moderation feature](#DOCS_RESOURCES_AUTO_MODERATION) which enables guilds to moderate message content based on keywords, harmful links, and unwanted spam. This change includes:
 
 * New endpoints for [creating](#DOCS_RESOURCES_AUTO_MODERATION/create-auto-moderation-rule), [updating](#DOCS_RESOURCES_AUTO_MODERATION/modify-auto-moderation-rule), and [deleting](#DOCS_RESOURCES_AUTO_MODERATION/delete-auto-moderation-rule) Auto Moderation rules
-* New gateway events emitted when Auto Moderation rules are [created](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-create) (`AUTO_MODERATION_RULE_CREATE`), [updated](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-update) (`AUTO_MODERATION_RULE_UPDATE `), and [deleted](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-delete) (`AUTO_MODERATION_RULE_DELETE `). Requires the `AUTO_MODERATION_CONFIGURATION` (`1 << 20`) intent
-* New gateway event emitted when an [action is executed](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-action-execution) (`AUTO_MODERATION_ACTION_EXECUTION`). Requires the `AUTO_MODERATION_EXECUTION` (`1 << 21`) intent
+* New gateway events emitted when Auto Moderation rules are [created](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-create) (`AUTO_MODERATION_RULE_CREATE`), [updated](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-update) (`AUTO_MODERATION_RULE_UPDATE `), and [deleted](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-delete) (`AUTO_MODERATION_RULE_DELETE `). Requires the `AUTO_MODERATION_CONFIGURATION` (`1 << 20`) intent
+* New gateway event emitted when an [action is executed](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-action-execution) (`AUTO_MODERATION_ACTION_EXECUTION`). Requires the `AUTO_MODERATION_EXECUTION` (`1 << 21`) intent
 * New [audit log entries](#DOCS_RESOURCES_AUDIT_LOG/audit-log-entry-object-audit-log-events) when rules are created (`AUTO_MODERATION_RULE_CREATE`), updated (`AUTO_MODERATION_RULE_UPDATE`), or deleted (`AUTO_MODERATION_RULE_DELETE`), or when Auto Moderation performs an action (`AUTO_MODERATION_BLOCK_MESSAGE`)