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

Agent skill: `npx skills add hookdeck/webhook-skills --skill discord-webhooks` ([details](https://hookdeck.com/webhooks/discord/skill))

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](/webhooks/discord) overview, every event type is on [Discord webhook events](/webhooks/discord/events), and signature verification code is on [Verify Discord webhooks](/webhooks/discord/verify).

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](#other-limits). To create your first incoming webhook, see [how to get started with Discord webhooks](/webhooks/platforms/how-to-get-started-with-discord-webhooks).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#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](#duplicates) | Build a key from the event type, its timestamp and an id in its data | Drops repeats before they reach your handler |
| [Ordering](#ordering) | Compare `event.timestamp`; fetch current state when order matters | Logs every event and attempt, so you can see arrival order when debugging |
| [Retries](#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](#choosing-events) | Subscribe only to what you process; use the Gateway for everything else | Filters and routes events by type |
| [Testing](#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](#other-limits) | 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 {#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](https://docs.discord.com/developers/events/webhook-events#responding-to-events). 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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
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](#retries) first.

## Duplicate Discord webhook events {#duplicates}

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](/webhooks/guides/implement-webhook-idempotency): the same result however many times it runs.

```python
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](/docs/deduplication) 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 {#ordering}

Discord [says](https://docs.discord.com/developers/events/webhook-events) 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](/webhooks/guides/webhook-ordering-why-its-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](https://docs.discord.com/developers/resources/entitlement#list-entitlements) as the source of truth when an event is ambiguous.
3. If you need realtime events in order, use a [Gateway connection](https://docs.discord.com/developers/events/gateway) 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 {#retries}

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](https://docs.discord.com/developers/events/webhook-events#responding-to-events). 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](https://docs.discord.com/developers/resources/application#application-object-application-event-webhook-status).

**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](/docs/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](/docs/authentication) list `401` responses for some source types only, and you can set the response body with a [custom response](/docs/sources#custom-responses). Register a test source and watch the result before you move production traffic.

## Choosing which Discord events to listen to {#choosing-events}

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](/webhooks/discord/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](https://docs.discord.com/developers/monetization/implementing-app-subscriptions), 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](/docs/filters) and routes events by type or any other property, so one Discord URL can feed several services.

## Testing and debugging Discord webhooks locally {#testing}

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](https://docs.discord.com/developers/quick-start/getting-started) 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](https://docs.discord.com/developers/resources/entitlement#create-test-entitlement) gives you an entitlement to delete, which fires `ENTITLEMENT_DELETE`.

**With Event Gateway:** [Hookdeck Inspect](https://inspect.hookdeck.com/webhooks/discord) shows sample Discord payloads with no account or setup. The [Hookdeck CLI](/docs/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 {#other-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](https://docs.discord.com/developers/topics/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](https://docs.discord.com/developers/resources/webhook#execute-webhook). 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](https://docs.discord.com/developers/resources/message#embed-object-embed-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](/docs/destinations#set-a-max-delivery-rate), Hookdeck queues what's above it and [retries](/docs/retries) failures, a [transformation](/docs/transformations) can turn another service's event into a Discord message, and your sources never see the Discord URL.