Learn how to receive Discord events over HTTP using webhooks.
Webhook events are one-way events sent to your app over HTTP to notify you when an event occurred. Unlike events that are sent over Gateway connections, events sent over webhooks are not realtime or guaranteed to be in order.While incoming webhooks are triggered by an external service, webhook events (i.e. outgoing webhooks) are triggered by events happening in Discord. This means your app will need to set up a public URL where you can receive HTTP events, which is detailed in the preparing for events section.
To configure webhook events, you’ll need to configure your URL and select the events you want your app to receive.
The steps below walk through subscribing using the developer portal. If you prefer to use the API, you can call Edit Current Application.
In your app’s settings, navigate to the Webhooks page from the left-hand sidebar then complete the following:
Under Endpoint, add a public URL that is set up to receive and acknowledge webhook events. Details about setting up a Webhook Events URL is in the preparing for events section.
Enable Events by clicking the toggle in the Events section.
A Webhook Events URL is a public endpoint for your app where Discord can send your app HTTP-based events. If your app is using Gateway events, you don’t need to configure a Webhook Events URL.
Before you can add a Webhook Events URL to your app, your endpoint must be prepared for two things ahead of time:
Acknowledging PING events from Discord
Validate security-related request headers (X-Signature-Ed25519 and X-Signature-Timestamp)
If either of these are not complete, your Webhook Events URL will not be validated. Details on acknowledging PING events and validating security-related headers are below.
Acknowledging PING requests
When adding your Webhook Events URL, Discord will send a POST request with a PING payload with a type: 0 to your endpoint. Your app is expected to acknowledge the request by returning a 204 response with an empty body.
You must provide a valid Content-Type when responding to PINGs. See here for further information.
Responding to PING Requests
Code example for acknowledging PING events
To properly acknowledge a PING payload, return a 204 response with no body:
Copy
Ask AI
@app.route('/', methods=['POST'])def my_command(): if request.json["type"] == 0: return Response(status=204)
Validating Security Request Headers
To receive events via HTTP, there are some security steps you must take before your app is eligible to receive requests.Each webhook is sent with the following headers:
X-Signature-Ed25519 as a signature
X-Signature-Timestamp as a timestamp
Using your favorite security library, you must validate the request each time you receive an event. If the signature fails validation, your app should respond with a 401 error code. Code examples of validating security headers is in the Interactions documentation.In addition to ensuring your app validates security-related request headers at the time of saving your endpoint, Discord will also perform automated, routine security checks against your endpoint, including purposefully sending you invalid signatures. If you fail the validation, we will remove your Webhook Events URL and alert you via email and System DM.We recommend checking out our Community Resources and the libraries found there.
After you have a public endpoint to use as your app’s Event Webhooks URL, you can add it to your app by going to your app’s settings.On the Webhooks page, look for the Endpoint URL field. Paste your public URL that is set up to acknowledge PING messages and correctly handles security-related signature headers.After you configure your Webhook Events URL, you can enable and subscribe to events on the same page.
When your Webhook Event URL receives a webhook event, your app should respond with a 204 status code with no body within 3 seconds to acknowledge that your app successfully received it. If your app doesn’t respond to the webhook event, Discord will retry sending it several times using exponential backoff for up to 10 minutes.If your app fails to respond too often, Discord will stop sending you webhook events and notify you via email.
The event body contains high-level data about the event, like the type and time it was triggered.The inner data object contains information specific to the event type.
The table below includes the different webhook event types your app can subscribe to.The “Value” column corresponds to the event’s type field value in the event body object.
ENTITLEMENT_CREATE is sent when an entitlement is created when a user purchases or is otherwise granted one of your app’s SKUs. Refer to the Monetization documentation for details.
Discord Social SDK utilizes specialized message objects for lobby and direct message events that occur during active game sessions. These objects extend or modify the standard Discord message structure to support communication features.
Lobby messages include lobby-specific fields like lobby_id
When both users in a direct message are provisional accounts, messages become “passthrough messages” that are only visible in-game and use this specialized structure.
