# Recharge webhooks in production: duplicates, retries and timeouts

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

This guide covers the problems Recharge webhooks cause in production and how to handle each one. What Recharge sends is on the [Recharge webhooks](/webhooks/recharge) overview, every topic is on [Recharge webhook events](/webhooks/recharge/events), and validation code is on [Verify Recharge webhooks](/webhooks/recharge/verify). Read that page before writing the check: every delivery carries two signatures, and the legacy `X-Recharge-Hmac-Sha256` header is not an HMAC.

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Respond 200 within 5 seconds; process asynchronously | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Dedupe on a payload identifier; make side effects idempotent | Drops repeats before they reach your handler |
| [Retries](#retries) | Keep the endpoint healthy; watch for deleted webhooks | Keeps accepting deliveries, so the webhook isn't deleted |
| [Choosing events](#choosing-events) | Subscribe to `charge/paid`, not `charge/success`, and only to topics you process | Filters and routes topics to the right service |
| [Testing](#testing) | Send real topics to a public URL that forwards to localhost | Forwards to localhost and replays past events |
| [Other limits](#other-limits) | Log every delivery; reconcile against the API | Stores every delivery for replay |

## Recharge webhook timeouts and slow handlers {#timeouts}

Recharge waits 5 seconds for a 200. Acknowledge first and process in a background job.

**Why it happens:** A handler that provisions access, syncs subscription state or triggers fulfilment before responding can pass 5 seconds. Recharge counts that as a failure, and every failure spends one of the 20 retries that stand between your endpoint and a deleted webhook.

**Fix it in your handler:**

1. Validate the signature against the raw body and return 200.
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 calls to other services out of the request path.

**With Event Gateway:** Hookdeck acknowledges Recharge immediately, then queues events and delivers them to your service at a rate it can handle.

## Duplicate Recharge webhooks {#duplicates}

The same event can arrive more than once across Recharge's 48-hour retry window. Dedupe on an identifier in the payload.

**Why it happens:** Recharge's at-least-once delivery favours not losing an event over sending it exactly once. With up to 20 retries over 48 hours, a delivery your handler processed but didn't acknowledge in time comes back, and acting on it twice can double-provision or double-charge downstream.

**Fix it in your handler:**

1. Dedupe on an event or resource identifier from the payload.
2. Make side effects idempotent. See our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency).

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) deliveries before they reach your handler, so the retry window doesn't turn into repeated processing.

## Recharge webhook retries and deleted webhooks {#retries}

After 20 failed retries over 48 hours, Recharge deletes the webhook subscription. From then on, a persistently failing endpoint receives nothing.

**Why it happens:** Recharge retries a delivery when there's no response or the response is a 408, 429 or 5xx. Once the retries are spent it prunes the subscription, treating the endpoint as permanently broken. Nothing more is sent until you recreate the webhook.

**Fix it in your handler:**

1. Acknowledge fast so transient slowness doesn't burn the retry budget.
2. Monitor for missing deliveries, and alert when a topic goes quiet.
3. Be ready to recreate a deleted webhook through the Admin API (`POST https://api.rechargeapps.com/webhooks` with an `address` and a `topic`).

**With Event Gateway:** Hookdeck always accepts deliveries from Recharge and handles downstream failures with its own [retries](/docs/retries), so an outage in your service never costs you the webhook.

## Choosing which Recharge topics to listen to {#choosing-events}

Use `charge/paid` for paid charges. There is no `charge/success` topic; if you see it referenced, it's a legacy name.

**Why it matters:** Recharge topics are slash-separated and scoped by resource: `subscription/created`, `charge/paid`, `order/processed`. Each webhook subscribes to one topic, so a wrong topic name means a webhook that never fires. The topics Recharge documents, with example payloads, are on [Recharge webhook events](/webhooks/recharge/events). Treat Recharge's own events reference as authoritative.

**Fix it in your handler:**

1. Subscribe only to the topics you process.
2. API versions `2021-01` and `2021-11` share tokens and topic names, so a topic name works across both.

**With Event Gateway:** Hookdeck [filters](/docs/filters) and routes topics to the right service from one source.

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

Recharge needs a public URL to deliver to. Forward deliveries to your local server rather than deploying to test.

**Why it happens:** Webhooks are created through the Admin API with a public `address`, and development machines aren't reachable from the internet. Validation also has to see the exact raw bytes Recharge sent.

**Fix it in your handler:**

1. Register a public forwarding URL as the webhook `address` for the topics you're testing.
2. Use the example payloads on [Recharge webhook events](/webhooks/recharge/events) as fixtures.
3. Test validation against the raw request body before any parsing.

**With Event Gateway:** The [Hookdeck CLI](/docs/cli) gives you a stable public URL that forwards to localhost, and you can replay past deliveries while you debug.

## Other Recharge webhook limits {#other-limits}

Recharge keeps no replayable delivery log, so once retries are exhausted or the webhook is deleted, missed events can't be recovered from Recharge.

**Fix it in your handler:**

1. Log every delivery you receive, so you have your own record.
2. Reconcile critical subscription and charge state against the Recharge API.

**With Event Gateway:** Hookdeck durably stores every delivery and supports replay, so recovery doesn't depend on Recharge's retry window.