Discord webhooks
Discord webhook events are signed HTTP POSTs Discord sends to your app's URL when something happens to your app, and they run the opposite way to incoming webhooks, which post messages into a channel.
These pages cover the events Discord sends your app. To post messages to a channel, see how to get started with Discord webhooks.
How Discord webhooks work
Webhook events tell your app about authorizations, entitlements and Social SDK messages without a Gateway connection or polling the API. You register one public URL for your app and choose event types, and Discord sends each event there as a signed JSON POST. Messages in ordinary channels, member joins and reactions aren't available this way, so those still need the Gateway.
The outer type is 0 for a PING and 1 for an event. In an event, event.type says what happened, such as ENTITLEMENT_CREATE, event.timestamp says when, and event.data holds the details. version is currently always 1. Incoming webhooks are a separate feature: you POST to a channel's URL and nothing is signed, so the events and signature pages here don't apply. Their limits are in the Production guide.
Key facts
{timestamp}{raw body} The X-Signature-Timestamp value with the raw body straight after it and no separator.
POST: answer the PING Discord sends a PING with type 0 when you save the URL. Answer 204 with an empty body.
Setting up Discord webhooks
- In your app's settings in the Developer Portal, open the Webhooks page, add your Endpoint URL, turn on Events and select the event types. The Edit Current Application API does the same.
- Prepare the endpoint first. Discord validates the URL with a
PING(type: 0) that needs a204with no body, and it checks signature handling, so a bad signature needs a401. - Test locally through a tunnel such as ngrok, which Discord's getting started guide uses. Discord's docs describe no way to resend an event, so log what you receive.
- To post messages to a channel instead, create an incoming webhook under Server Settings, then Integrations.
Delivery behaviour
3 seconds respond with a 204 and no body Retries up to 10 minutes several attempts with exponential backoff; the count isn't published After repeated failures events stop Discord notifies you by email; the threshold isn't published Ordering not guaranteed Discord also says webhook events aren't realtime Known failure modes
From Hookdeck's Discord guide →-
A failed security check removes your URL
Discord sends deliberately invalid signatures to test your endpoint. If it doesn't reject them, Discord removes your Webhook Events URL and alerts you by email and System DM.
Retries and losing your endpoint → -
An outage longer than 10 minutes loses events
Discord retries an unanswered event for up to 10 minutes and documents no way to resend it. After an outage, reconcile entitlements from the List Entitlements API.
Retries and losing your endpoint → -
Out-of-order delivery
Discord says webhook events aren't realtime or guaranteed to be in order. Compare
Handle ordering →event.timestamp, and fetch current state from the API when order matters. -
An Interactions handler drops webhook events
An Interactions
Testing your endpoint →PINGistype: 1, but on a Webhook Events URLtype: 1is a real event. A handler copied from an Interactions example answers every event with aPONGand processes none.
Discord webhook best practices
- Verify every signature. Reject failures with a 401, because Discord sends invalid signatures on purpose and removes URLs that accept them.
- Respond within 3 seconds. Return a 204 with no body and move the work to a queue, so slow processing doesn't trigger retries.
- Build your own dedupe key. The payload has no delivery id, so combine the event type, its timestamp and an id from its data.
- Watch your endpoint's status. Check event_webhooks_status on your application, because Discord can stop delivery and its notices go by email and System DM.
- Subscribe only to events you process. Webhook events cover authorizations, entitlements and Social SDK messages. Use the Gateway for anything else.
- Post to channels within rate limits. For incoming webhooks, read the rate limit headers rather than hard-coding a limit, and wait for retry_after after a 429.
Common Discord webhook events
Authorizations
APPLICATION_AUTHORIZED | User adds your app to a server or their account |
APPLICATION_DEAUTHORIZED | Your app loses a user's authorization |
Entitlements
ENTITLEMENT_CREATE | User buys or receives one of your SKUs |
ENTITLEMENT_UPDATE | Entitlement changes, such as a subscription ending |
ENTITLEMENT_DELETE | Refund, Discord removal or test deletion ends an entitlement |
Social SDK messages
LOBBY_MESSAGE_CREATE | New message posted in a lobby |
GAME_DIRECT_MESSAGE_CREATE | DM sent during an active Social SDK session |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
entitlement | 3 | 3 |
game_direct_message | 3 | 3 |
lobby_message | 3 | 3 |
1 more resource, including Other Discord events. All 12 events →
In this hub
| Webhook events → | Every covered Discord event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Discord events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill discord-webhooks |
Stop rate limits and outages losing your Discord messages.
Hookdeck Event Gateway queues what you send to a Discord webhook URL, delivers it at a rate you set and retries failures, with a log of every attempt.