Discord webhooks in production: duplicates, ordering, retries and timeouts
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
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 204 with no body within 3 seconds; process in a background job | Queues events and delivers them to your service at a rate you set |
| Duplicates | Build a key from the event type, its timestamp and an id in its data | Drops repeats before they reach your handler |
| Ordering | Compare event.timestamp; fetch current state when order matters | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Pass the security checks, watch event_webhooks_status, reconcile after an outage | Holds events and retries them, once your source passes Discord's checks |
| Choosing events | Subscribe only to what you process; use the Gateway for everything else | Filters and routes events by type |
| Testing | Tunnel to localhost; keep Interactions and webhook events on separate handlers | Sample payloads in Inspect, and forwarding and replay with the CLI |
| Posting to a channel | Read rate limit headers, use ?wait=true, keep the URL secret | Queues 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:
- Verify the signature and return the
204straight away. - Push the event onto a queue and process it in a worker. See why to process webhooks asynchronously.
- 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:
- Build a key from
event.type,event.timestampand an id fromevent.data: the entitlement or messageid, oruser.idfor authorization events. Discord defines the timestamp as when the event occurred, so it should hold across retries, but the docs don't promise that. - Store processed keys in a table with a unique constraint.
- 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:
- Compare
event.timestampbefore you apply an update, so an older event can't overwrite newer state. - For entitlements, treat List Entitlements as the source of truth when an event is ambiguous.
- 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_DISCORDstatus means Discord disabled webhook events, usually because of inactivity.
Fix it in your handler:
- Reject every invalid signature with a
401, on every request, including ones that look like aPING. - Monitor
event_webhooks_statusfromGET /applications/@me.2means enabled and3means Discord disabled it. - Make sure someone reads the emails and System DMs Discord sends about your app.
- 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:
- List the events your code handles and select exactly those on your app's Webhooks page.
- Route on the outer
typefirst. APINGhas noeventobject, so readingevent.typeon it throws. - Don't wait for an event when a user cancels a subscription. Discord sends no entitlement event at that point, only an
ENTITLEMENT_UPDATEwithends_atwhen the subscription ends. Refunds and removals sendENTITLEMENT_DELETE. - 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:
- Expose your local server with a tunnel such as ngrok, which Discord's getting started guide uses.
- Save the URL on your app's Webhooks page and confirm it validates.
- Send your endpoint a request with a bad signature, and check it gets a
401. - Generate real events. Adding your app from another account fires
APPLICATION_AUTHORIZED, and Create Test Entitlement gives you an entitlement to delete, which firesENTITLEMENT_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.