Discord webhooks in production: duplicates, ordering, retries and timeouts

Published · Updated

This guide covers the problems Discord webhooks cause in production and how to handle each one. What Discord sends and how it's signed is on the Discord webhooks overview, every event type is on Discord webhook events, and signature verification code is on Verify Discord webhooks.

Discord uses the word webhook for two features that run in opposite directions. Webhook events are requests Discord sends to your URL, and most of this guide is about them. Incoming webhooks are requests you send to a channel's URL, and their limits are in Posting to a channel. To create your first incoming webhook, see how to get started with Discord webhooks.

At a glance

ProblemWhat to doWith Event Gateway
TimeoutsReturn a 204 with no body within 3 seconds; process in a background jobQueues events and delivers them to your service at a rate you set
DuplicatesBuild a key from the event type, its timestamp and an id in its dataDrops repeats before they reach your handler
OrderingCompare event.timestamp; fetch current state when order mattersLogs every event and attempt, so you can see arrival order when debugging
RetriesPass the security checks, watch event_webhooks_status, reconcile after an outageHolds events and retries them, once your source passes Discord's checks
Choosing eventsSubscribe only to what you process; use the Gateway for everything elseFilters and routes events by type
TestingTunnel to localhost; keep Interactions and webhook events on separate handlersSample payloads in Inspect, and forwarding and replay with the CLI
Posting to a channelRead rate limit headers, use ?wait=true, keep the URL secretQueues your messages and delivers them at a rate you set

Discord webhook event timeouts

Respond with a 204 and no body within 3 seconds, then do the work in a background job.

Why it happens: Discord asks for that response within 3 seconds. If it doesn't get one, it retries the event, and if your app fails to respond too often it stops sending events altogether. Handlers that write to a database or call other APIs before responding are the usual cause.

Fix it in your handler:

  1. Verify the signature and return the 204 straight away.
  2. Push the event onto a queue and process it in a worker. See why to process webhooks asynchronously.
  3. Keep the request path free of calls to other services, including the Discord API.

With Event Gateway: Hookdeck accepts each delivery, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take as long as it needs. Check what Discord's checks need from your source first.

Duplicate Discord webhook events

Assume an event can arrive more than once, and build your own dedupe key, because the payload has no delivery id.

Why it happens: Discord retries an event it didn't get a response to, so a handler that finishes its work and then responds late can see the same event again. Discord's docs don't mention duplicates or a delivery guarantee. The outer payload holds only version, application_id, type and event, and an event like APPLICATION_AUTHORIZED has no id of its own.

Fix it in your handler:

  1. Build a key from event.type, event.timestamp and an id from event.data: the entitlement or message id, or user.id for authorization events. Discord defines the timestamp as when the event occurred, so it should hold across retries, but the docs don't promise that.
  2. Store processed keys in a table with a unique constraint.
  3. Make every handler idempotent: the same result however many times it runs.
def dedupe_key(payload):
    event = payload["event"]
    data = event.get("data") or {}
    subject = data.get("id") or (data.get("user") or {}).get("id")
    return f"{event['type']}:{subject}:{event['timestamp']}"

With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.

Out-of-order Discord webhook events

Discord says webhook events aren't realtime or guaranteed to be in order. Don't rely on arrival order.

Why it happens: Webhook events are one-way HTTP requests, retried separately, so a later event can arrive first. An ENTITLEMENT_UPDATE could follow the ENTITLEMENT_DELETE for the same entitlement. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.

Fix it in your handler:

  1. Compare event.timestamp before you apply an update, so an older event can't overwrite newer state.
  2. For entitlements, treat List Entitlements as the source of truth when an event is ambiguous.
  3. If you need realtime events in order, use a Gateway connection instead.

With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.

Discord webhook retries and losing your endpoint

Discord retries for only 10 minutes, and it can stop delivery in three separate ways. Keep the endpoint up, watch its status, and reconcile after any outage.

Why it happens: If your app doesn't respond, Discord retries several times with exponential backoff for up to 10 minutes. It doesn't publish the number of attempts, and its docs describe no way to resend an event, so an outage longer than that loses events. Delivery can also stop altogether:

  • Too many failures. If your app fails to respond too often, Discord stops sending events and notifies you by email. The threshold isn't published.
  • A failed security check. Discord routinely sends invalid signatures to your endpoint. If you don't reject them, it removes your Webhook Events URL and alerts you by email and System DM.
  • Inactivity. The DISABLED_BY_DISCORD status means Discord disabled webhook events, usually because of inactivity.

Fix it in your handler:

  1. Reject every invalid signature with a 401, on every request, including ones that look like a PING.
  2. Monitor event_webhooks_status from GET /applications/@me. 2 means enabled and 3 means Discord disabled it.
  3. Make sure someone reads the emails and System DMs Discord sends about your app.
  4. After an outage, reconcile what the API can tell you. List Entitlements covers purchases and grants.

With Event Gateway: Hookdeck holds events while your service is down and retries them on your schedule, well past Discord's 10 minutes. Discord validates the Source URL itself, though, so confirm your source passes before you rely on this. Discord wants a 204 for a PING and a 401 for a bad signature. Hookdeck's docs list 401 responses for some source types only, and you can set the response body with a custom response. Register a test source and watch the result before you move production traffic.

Choosing which Discord events to listen to

Subscribe only to the events you process. Webhook events cover app authorizations, entitlements and Social SDK messages, and everything else needs the Gateway.

Why it matters: Messages in ordinary channels, member joins, role changes and reactions aren't available as webhook events. QUEST_USER_ENROLLMENT appears on the settings page, but Discord says apps can't receive it yet. The full list, with sample payloads, is on Discord webhook events.

Fix it in your handler:

  1. List the events your code handles and select exactly those on your app's Webhooks page.
  2. Route on the outer type first. A PING has no event object, so reading event.type on it throws.
  3. Don't wait for an event when a user cancels a subscription. Discord sends no entitlement event at that point, only an ENTITLEMENT_UPDATE with ends_at when the subscription ends. Refunds and removals send ENTITLEMENT_DELETE.
  4. In a Social SDK app, subscribe to APPLICATION_DEAUTHORIZED. Discord calls it the only out-of-game signal that a user's link state has changed.

With Event Gateway: Hookdeck filters and routes events by type or any other property, so one Discord URL can feed several services.

Testing and debugging Discord webhooks locally

Test through a tunnel that returns your handler's response to Discord, and keep webhook events and Interactions on separate handlers.

Why it happens: Discord needs a public URL, and it validates that URL when you save it, so your handler has to answer the PING at that moment. The two features also use the same numbers for different things. An Interactions PING is type: 1 and wants a 200 with a PONG. A Webhook Events PING is type: 0 and wants a 204, and on that URL type: 1 means a real event. A handler copied from an Interactions example answers every event with a PONG and processes none of them.

Fix it in your handler:

  1. Expose your local server with a tunnel such as ngrok, which Discord's getting started guide uses.
  2. Save the URL on your app's Webhooks page and confirm it validates.
  3. Send your endpoint a request with a bad signature, and check it gets a 401.
  4. Generate real events. Adding your app from another account fires APPLICATION_AUTHORIZED, and Create Test Entitlement gives you an entitlement to delete, which fires ENTITLEMENT_DELETE.

With Event Gateway: Hookdeck Inspect shows sample Discord payloads with no account or setup. The Hookdeck CLI forwards events to your machine and replays past ones. Hookdeck answers Discord itself, so your local handler's 204 and 401 don't reach Discord, and validating your own handler still needs a direct tunnel.

Posting to a channel: incoming webhook limits

Incoming webhooks have no signatures, retries or delivery log on Discord's side, because you're the sender. Handle rate limits and failures in your own code, and keep the URL secret.

Rate limits. Discord says not to hard-code rate limits, because they can change. Read the X-RateLimit-* response headers, group shared limits by X-RateLimit-Bucket, and after a 429 wait for Retry-After or retry_after.

Temporary IP bans. An IP address that makes 10,000 requests in 10 minutes ending in 401, 403 or 429 is temporarily restricted from the Discord API. Webhook calls with no authorization header are limited by IP, which matters on shared cloud addresses. If a webhook returns 404, stop using it, because repeated attempts also lead to a restriction. A 429 with X-RateLimit-Scope: shared doesn't count against you.

Failed sends. Discord doesn't retry for you, so retry from your own code with backoff, and log each response. By default a message that isn't saved returns no error. Add ?wait=true when delivery matters: Discord confirms the send and returns the created message.

The URL is the credential. It contains the webhook's token, and anyone who has it can post to your channel. Keep it out of source control, limit who has the MANAGE_WEBHOOKS permission, and delete the webhook if the URL leaks.

Mentions in relayed content. Text from another system can contain @everyone or role mentions. Set allowed_mentions to control which ones ping, since Discord warns about unexpected mentions in user-generated content.

Message limits. content takes up to 2,000 characters and a message up to 10 embeds. Embed fields have their own limits, and the combined total across all of a message's embeds can't exceed 6,000 characters. Split longer content across messages.

Webhook names. A name can't contain clyde or discord in any case, and can be up to 80 characters. Validate names before you create webhooks through the API.

With Event Gateway: Send to Hookdeck and make your Discord URL its destination. You set a maximum delivery rate, Hookdeck queues what's above it and retries failures, a transformation can turn another service's event into a Discord message, and your sources never see the Discord URL.

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.