# 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](/webhooks/platforms/how-to-get-started-with-discord-webhooks).

Agent skill: `npx skills add hookdeck/webhook-skills --skill discord-webhooks` ([details](https://hookdeck.com/webhooks/discord/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Discord's official docs](https://docs.discord.com/developers/events/webhook-events).

[Overview](https://hookdeck.com/webhooks/discord) · [Webhook events (12)](https://hookdeck.com/webhooks/discord/events) · [MCP events](https://hookdeck.com/webhooks/discord/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/discord/verify) · [Production guide](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/discord/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Signature-Ed25519` Format: <hex> | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| Scheme | `Ed25519` Asymmetric: verify with the vendor's public key. | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| Signed material | `{timestamp}{raw body}` The X-Signature-Timestamp value with the raw body straight after it and no separator. | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| How events are identified | `event.type field in the body` | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| Body format | `JSON` | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| API versioning | `version in the body` | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| Send timestamp | `X-Signature-Timestamp` | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| URL handshake | `POST: answer the PING` Discord sends a PING with type 0 when you save the URL. Answer 204 with an empty body. | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| Envelope | `version, application_id, type, event` | [Discord docs](https://docs.discord.com/developers/events/webhook-events) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill discord-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/discord/skill) |

[Verify Discord webhooks](https://hookdeck.com/webhooks/discord/verify)

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

## 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 a `204` with no body, and it checks signature handling, so a bad signature needs a `401`.
- 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

- **Timeout:** 3 seconds. respond with a 204 and no body. [Guide](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 10 minutes. several attempts with exponential backoff; the count isn't published. [Guide](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#retries)
- **After repeated failures:** events stop. Discord notifies you by email; the threshold isn't published. [Guide](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. Discord also says webhook events aren't realtime. [Guide](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **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](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#retries)
2. **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](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#retries)
3. **Out-of-order delivery.** Discord says webhook events aren't realtime or guaranteed to be in order. Compare `event.timestamp`, and fetch current state from the API when order matters. [Handle ordering](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#ordering)
4. **An Interactions handler drops webhook events.** An Interactions `PING` is `type: 1`, but on a Webhook Events URL `type: 1` is a real event. A handler copied from an Interactions example answers every event with a `PONG` and processes none. [Testing your endpoint](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#testing)

From [Hookdeck's Discord guide](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts).

## Discord webhook best practices

- **[Verify every signature](https://hookdeck.com/webhooks/discord/verify).** Reject failures with a 401, because Discord sends invalid signatures on purpose and removes URLs that accept them.
- **[Respond within 3 seconds](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#duplicates).** The payload has no delivery id, so combine the event type, its timestamp and an id from its data.
- **[Watch your endpoint's status](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#choosing-events).** Webhook events cover authorizations, entitlements and Social SDK messages. Use the Gateway for anything else.
- **[Post to channels within rate limits](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts#other-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](https://hookdeck.com/webhooks/discord/events#APPLICATION_AUTHORIZED): User adds your app to a server or their account
- [APPLICATION_DEAUTHORIZED](https://hookdeck.com/webhooks/discord/events#APPLICATION_DEAUTHORIZED): Your app loses a user's authorization

### Entitlements

- [ENTITLEMENT_CREATE](https://hookdeck.com/webhooks/discord/events#ENTITLEMENT_CREATE): User buys or receives one of your SKUs
- [ENTITLEMENT_UPDATE](https://hookdeck.com/webhooks/discord/events#ENTITLEMENT_UPDATE): Entitlement changes, such as a subscription ending
- [ENTITLEMENT_DELETE](https://hookdeck.com/webhooks/discord/events#ENTITLEMENT_DELETE): Refund, Discord removal or test deletion ends an entitlement

### Social SDK messages

- [LOBBY_MESSAGE_CREATE](https://hookdeck.com/webhooks/discord/events#LOBBY_MESSAGE_CREATE): New message posted in a lobby
- [GAME_DIRECT_MESSAGE_CREATE](https://hookdeck.com/webhooks/discord/events#GAME_DIRECT_MESSAGE_CREATE): DM sent during an active Social SDK session

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [entitlement](https://hookdeck.com/webhooks/discord/events#resource-entitlement) | 3 | 3 |
| [game_direct_message](https://hookdeck.com/webhooks/discord/events#resource-game-direct-message) | 3 | 3 |
| [lobby_message](https://hookdeck.com/webhooks/discord/events#resource-lobby-message) | 3 | 3 |

1 more resource. [All 12 events](https://hookdeck.com/webhooks/discord/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/discord/events): Every covered Discord event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/discord/mcp-events): How an agent subscribes to Discord events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/discord/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/discord/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/discord/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill discord-webhooks`
---

Not affiliated with Discord. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/discord.json) · [Report a correction](https://hookdeck.com/contact)
