Recharge webhooks in production: duplicates, retries and timeouts
This guide covers the problems Recharge webhooks cause in production and how to handle each one. What Recharge sends is on the Recharge webhooks overview, every topic is on Recharge webhook events, and validation code is on Verify Recharge webhooks. 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 | Respond 200 within 5 seconds; process asynchronously | Accepts the delivery at once, then queues it for your service |
| Duplicates | Dedupe on a payload identifier; make side effects idempotent | Drops repeats before they reach your handler |
| Retries | Keep the endpoint healthy; watch for deleted webhooks | Keeps accepting deliveries, so the webhook isn't deleted |
| Choosing events | Subscribe to charge/paid, not charge/success, and only to topics you process | Filters and routes topics to the right service |
| Testing | Send real topics to a public URL that forwards to localhost | Forwards to localhost and replays past events |
| Other limits | Log every delivery; reconcile against the API | Stores every delivery for replay |
Recharge webhook timeouts and slow handlers
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:
- Validate the signature against the raw body and return 200.
- Push the event onto a queue and process it in a worker. See why to process webhooks asynchronously.
- 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
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:
- Dedupe on an event or resource identifier from the payload.
- Make side effects idempotent. See our guide to webhook idempotency.
With Event Gateway: Hookdeck deduplicates deliveries before they reach your handler, so the retry window doesn't turn into repeated processing.
Recharge webhook retries and deleted webhooks
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:
- Acknowledge fast so transient slowness doesn't burn the retry budget.
- Monitor for missing deliveries, and alert when a topic goes quiet.
- Be ready to recreate a deleted webhook through the Admin API (
POST https://api.rechargeapps.com/webhookswith anaddressand atopic).
With Event Gateway: Hookdeck always accepts deliveries from Recharge and handles downstream failures with its own retries, so an outage in your service never costs you the webhook.
Choosing which Recharge topics to listen to
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. Treat Recharge's own events reference as authoritative.
Fix it in your handler:
- Subscribe only to the topics you process.
- API versions
2021-01and2021-11share tokens and topic names, so a topic name works across both.
With Event Gateway: Hookdeck filters and routes topics to the right service from one source.
Testing and debugging Recharge webhooks locally
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:
- Register a public forwarding URL as the webhook
addressfor the topics you're testing. - Use the example payloads on Recharge webhook events as fixtures.
- Test validation against the raw request body before any parsing.
With Event Gateway: The Hookdeck CLI gives you a stable public URL that forwards to localhost, and you can replay past deliveries while you debug.
Other Recharge webhook 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:
- Log every delivery you receive, so you have your own record.
- 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.
Keep a failing endpoint from losing its Recharge webhook.
Hookdeck Event Gateway acknowledges Recharge within the 5-second window, verifies the signature, deduplicates, and retries to your service on your schedule.