Skip to main content
Webhook events are one-way events sent to your app over HTTP to notify you when an event occurred. Unlike Gateway events, events sent over webhooks are not realtime and are not guaranteed to be in order.
While incoming webhooks are triggered by an external service, webhook events (outgoing webhooks) are triggered by events happening in Discord. Your app needs a public URL to receive HTTP events.

​
Subscribing to Events

To configure webhook events, configure your URL and select the events you want your app to receive.
The steps below walk through subscribing using the developer portal. To use the API instead, call Edit Current Application.
In your app’s settings, navigate to the Webhooks page and complete the following:
  1. Under Endpoint, add a public URL set up to receive and acknowledge webhook events.
  2. Enable events by clicking the toggle in the Events section.
  3. Select the webhook events you want your app to receive.
  4. Click Save Changes.
If your URL is successfully verified, your app will begin receiving the events you selected.

​
Preparing for Events

​
Configuring a Webhook Events URL

A Webhook Events URL is a public endpoint for your app where Discord sends HTTP-based events. If your app is using Gateway events, you don’t need to configure a Webhook Events URL.

​
Setting Up an Endpoint

Before adding a Webhook Events URL, your endpoint must handle two things:
  1. Acknowledging PING events from Discord
  2. Validating security-related request headers (X-Signature-Ed25519 and X-Signature-Timestamp)
If either of these are incomplete, your Webhook Events URL will not be validated.

​
Acknowledging PING Requests

When adding your Webhook Events URL, Discord sends a POST request with a PING payload (type: 0) to your endpoint. Acknowledge it by returning a 204 response with an empty body.
You must provide a valid Content-Type when responding to PINGs.
Return a 204 response with no body:
@app.route('/', methods=['POST'])
def my_command():
    if request.json["type"] == 0:
        return Response(status=204)

​
Validating Security Request Headers

Each webhook is sent with the following headers:
  • X-Signature-Ed25519 — signature
  • X-Signature-Timestamp — timestamp
You must validate the request each time you receive an event. If validation fails, respond with a 401 error. Code examples are in the Interactions documentation.
Discord performs automated security checks against your endpoint, including intentionally sending invalid signatures. If validation fails, Discord will remove your Webhook Events URL and alert you via email and System DM.

​
Adding a Webhook Events Endpoint URL

After your endpoint is set up, go to your app’s settings, open the Webhooks page, and paste your public URL in the Endpoint URL field.

​
Responding to Events

When your Webhook Event URL receives a webhook event, respond with a 204 status code and no body within 3 seconds. If your app doesn’t respond in time, Discord retries using exponential backoff for up to 10 minutes.
If your app fails to respond too often, Discord will stop sending webhook events and notify you via email.

​
Webhook Event Payloads

Webhook events are wrapped in an outer payload with an inner event object.

​
Payload Structure

FieldTypeDescription
versionintegerVersion scheme for the webhook event. Currently always 1
application_idsnowflakeID of your app
typewebhook typeType of webhook, either 0 for PING or 1 for webhook events
event?event body objectEvent data payload

​
Webhook Types

TypeValueDescription
PING0PING event sent to verify your Webhook Event URL is active
Event1Webhook event (details in the event body object)

​
Event Body Object

The event body contains high-level data about the event. The inner data object contains information specific to the event type.
FieldTypeDescription
typestringEvent type
timestampstringTimestamp of when the event occurred in ISO8601 format
data?objectData for the event. The shape depends on the event type

​
Event Types

The table below includes the different webhook event types your app can subscribe to. The “Value” column corresponds to the event’s type field in the event body object.
NameValueDescription
Application AuthorizedAPPLICATION_AUTHORIZEDSent when an app was authorized by a user to a server or their account
Application DeauthorizedAPPLICATION_DEAUTHORIZEDSent when an app was deauthorized by a user
Entitlement CreateENTITLEMENT_CREATEEntitlement was created
Entitlement UpdateENTITLEMENT_UPDATEEntitlement was updated
Entitlement DeleteENTITLEMENT_DELETEEntitlement was deleted
Quest User EnrollmentQUEST_USER_ENROLLMENTUser was added to a Quest (currently unavailable)
Lobby Message CreateLOBBY_MESSAGE_CREATESent when a message is created in a lobby
Lobby Message UpdateLOBBY_MESSAGE_UPDATESent when a message is updated in a lobby
Lobby Message DeleteLOBBY_MESSAGE_DELETESent when a message is deleted from a lobby
Game Direct Message CreateGAME_DIRECT_MESSAGE_CREATESent when a direct message is created during an active Social SDK session
Game Direct Message UpdateGAME_DIRECT_MESSAGE_UPDATESent when a direct message is updated during an active Social SDK session
Game Direct Message DeleteGAME_DIRECT_MESSAGE_DELETESent when a direct message is deleted during an active Social SDK session

​
Application Authorized

APPLICATION_AUTHORIZED is sent when the app is added to a server or user account.

​
Application Authorized Structure

FieldTypeDescription
integration_type?integerInstallation context. Guild (0) or user (1)
useruser objectUser who authorized the app
scopesarray of stringsList of OAuth2 scopes the user authorized
guild?guild objectServer which app was authorized for (when integration type is 0)
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "APPLICATION_AUTHORIZED",
    "timestamp": "2024-10-18T14:42:53.064834",
    "data": {
      "integration_type": 1,
      "scopes": [
        "applications.commands"
      ],
      "user": {}
    }
  }
}

​
Application Deauthorized

APPLICATION_DEAUTHORIZED is sent when the app is deauthorized by a user.
FieldTypeDescription
useruser objectUser who deauthorized the app
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "APPLICATION_DEAUTHORIZED",
    "timestamp": "2024-10-18T14:42:53.064834",
    "data": {
      "user": {}
    }
  }
}

​
Entitlement Create

ENTITLEMENT_CREATE is sent when an entitlement is created when a user purchases or is otherwise granted one of your app’s SKUs. See Monetization documentation for details. The inner payload is an entitlement object. 
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "ENTITLEMENT_CREATE",
    "timestamp": "2024-10-18T18:41:21.109604",
    "data": {
      "application_id": "1234560123453231555",
      "consumed": false,
      "deleted": false,
      "gift_code_flags": 0,
      "id": "1234505980407808808",
      "promotion_id": null,
      "sku_id": "123489045643835123",
      "type": 4,
      "user_id": "111178765189277770"
    }
  }
}

​
Entitlement Update

ENTITLEMENT_UPDATE is sent when an entitlement is updated. The inner payload is an entitlement object. 
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "ENTITLEMENT_UPDATE",
    "timestamp": "2024-10-18T18:41:21.109604",
    "data": {
      "application_id": "1234560123453231555",
      "consumed": false,
      "deleted": false,
      "gift_code_flags": 0,
      "id": "1234505980407808808",
      "promotion_id": null,
      "sku_id": "123489045643835123",
      "type": 4,
      "user_id": "111178765189277770"
    }
  }
}

​
Entitlement Delete

ENTITLEMENT_DELETE is sent when an entitlement is deleted. The inner payload is an entitlement object. 
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "ENTITLEMENT_DELETE",
    "timestamp": "2024-10-18T18:41:21.109604",
    "data": {
      "application_id": "1234560123453231555",
      "consumed": false,
      "deleted": true,
      "gift_code_flags": 0,
      "id": "1234505980407808808",
      "promotion_id": null,
      "sku_id": "123489045643835123",
      "type": 4,
      "user_id": "111178765189277770"
    }
  }
}

​
Quest User Enrollment

This event cannot be received by apps at this time. It’s documented because it appears on the Webhooks settings page.
QUEST_USER_ENROLLMENT is sent when a user is added to a Quest on Discord.

​
Lobby Message Create

LOBBY_MESSAGE_CREATE is sent when a message is created in a lobby. The inner payload is a lobby message object. 
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "LOBBY_MESSAGE_CREATE",
    "timestamp": "2024-10-18T18:41:21.109604",
    "data": {
      "id": "1397729799727878254",
      "type": 0,
      "content": "welcome to the party!",
      "lobby_id": "1397729744753266719",
      "channel_id": "1397729744753266719",
      "author": {},
      "flags": 65536,
      "application_id": "1234567765431056709"
    }
  }
}

​
Lobby Message Update

LOBBY_MESSAGE_UPDATE is sent when a message is updated in a lobby. The inner payload is a lobby message object with additional fields for message updates. 
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "LOBBY_MESSAGE_UPDATE",
    "timestamp": "2025-08-05T20:39:19.587872",
    "data": {
      "id": "1402390388030832792",
      "type": 0,
      "content": "noice",
      "lobby_id": "1402385687281537066",
      "channel_id": "1402389638311841883",
      "author": {},
      "edited_timestamp": "2025-08-05T20:39:19.557970+00:00",
      "flags": 0,
      "timestamp": "2025-08-05T20:38:43.660000+00:00"
    }
  }
}

​
Lobby Message Delete

LOBBY_MESSAGE_DELETE is sent when a message is deleted from a lobby.
FieldTypeDescription
idsnowflakeID of the deleted message
lobby_idsnowflakeID of the lobby where the message was deleted
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "LOBBY_MESSAGE_DELETE",
    "timestamp": "2025-08-05T21:44:09.412957",
    "data": {
      "id": "1402406637632884857",
      "lobby_id": "1402399883394285659"
    }
  }
}

​
Game Direct Message Create

GAME_DIRECT_MESSAGE_CREATE is sent when a direct message is created while at least one user has an active Social SDK session. The inner payload is a message object or SDK DM message object. 
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "GAME_DIRECT_MESSAGE_CREATE",
    "timestamp": "2025-08-14T18:09:38.063234",
    "data": {
      "id": "1405614357781545021",
      "type": 0,
      "content": "get in friend, we're going raiding",
      "channel_id": "1405604229820715098",
      "author": {},
      "timestamp": "2025-08-14T18:09:37.947000+00:00",
      "application_id": "1234567765431056709",
      "attachments": []
    }
  }
}

​
Game Direct Message Update

GAME_DIRECT_MESSAGE_UPDATE is sent when a direct message is updated while at least one user has an active Social SDK session. The inner payload is a message object or SDK DM message object. 
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "GAME_DIRECT_MESSAGE_UPDATE",
    "timestamp": "2025-08-14T16:44:31.847073",
    "data": {
      "id": "1405591838810706081",
      "content": "almost ready to queue?",
      "channel_id": "1404960877324533784",
      "author": {},
      "recipient_id": "1404960877324533784"
    }
  }
}

​
Game Direct Message Delete

GAME_DIRECT_MESSAGE_DELETE is sent when a direct message is deleted while at least one user has an active Social SDK session. The inner payload is a message object or SDK DM message object. 
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "GAME_DIRECT_MESSAGE_DELETE",
    "timestamp": "2025-08-20T17:01:50.099204",
    "data": {
      "id": "1407771600643686503",
      "type": 0,
      "content": "cant make it in time",
      "channel_id": "1405604229820715098",
      "author": {},
      "timestamp": "2025-08-20T17:01:44.725000+00:00",
      "flags": 0,
      "attachments": [],
      "components": []
    }
  }
}

​
Social SDK Message Objects

Discord Social SDK uses specialized message objects for lobby and direct message events during active game sessions.

​
Lobby Message Object

Represents a message sent in a lobby or Linked Channel.
FieldTypeDescription
idsnowflakeID of the message
typeintegerType of message
contentstringContents of the message
lobby_idsnowflakeID of the lobby where the message was sent
channel_idsnowflakeID of the channel the message was sent in
authoruser objectAuthor of the message
metadata?objectAdditional metadata for the message (key-value pairs)
flagsintegerMessage flags combined as a bitfield
application_id?snowflakeID of the application (only present during active Social SDK sessions)

​
Message Object

Standard Message Object with additional fields.
FieldTypeDescription
lobby_id?snowflakeID of the lobby where the message was created (only present in Linked Channel messages)
channelchannel objectChannel object with recipient information

​
SDK DM Message Object

Represents a message between provisional users that exists only in-game.
When both users in a direct message are provisional accounts, messages become “SDK DM messages” that are only visible in-game.
FieldTypeDescription
idsnowflakeID of the message
typeintegerType of message
contentstringContents of the message
authoruser objectAuthor of the message
flagsintegerMessage flags combined as a bitfield
application_idsnowflakeID of the application that created the message
channelchannel objectChannel object with recipient information
activity?message activity objectSent with Rich Presence-related chat embeds
application?partial applicationSent with Rich Presence-related chat embeds