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.

12 events covered

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

Signature header
X-Signature-Ed25519

Format: <hex>

Scheme
Ed25519

Asymmetric: verify with the vendor's public key.

Signed material
{timestamp}{raw body}

The X-Signature-Timestamp value with the raw body straight after it and no separator.

How events are identified
event.type field in the body
Body format
JSON
API versioning
version in the body
Send timestamp
X-Signature-Timestamp
URL handshake
POST: answer the PING

Discord sends a PING with type 0 when you save the URL. Answer 204 with an empty body.

Envelope
version, application_id, type, event
Agent skill
npx skills add hookdeck/webhook-skills --skill discord-webhooks

Verify Discord webhooks →

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

  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 →
  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 →
  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 →
  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 →

Discord webhook best practices

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

ENTITLEMENT_CREATE · ENTITLEMENT_UPDATE · ENTITLEMENT_DELETE

3 3
game_direct_message

GAME_DIRECT_MESSAGE_CREATE · GAME_DIRECT_MESSAGE_UPDATE · GAME_DIRECT_MESSAGE_DELETE

3 3
lobby_message

LOBBY_MESSAGE_CREATE · LOBBY_MESSAGE_UPDATE · LOBBY_MESSAGE_DELETE

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.

Not affiliated with Discord. Facts are compiled from public sources and linked inline.