Recharge webhooks in production: duplicates, retries and timeouts

Published · Updated

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

ProblemWhat to doWith Event Gateway
TimeoutsRespond 200 within 5 seconds; process asynchronouslyAccepts the delivery at once, then queues it for your service
DuplicatesDedupe on a payload identifier; make side effects idempotentDrops repeats before they reach your handler
RetriesKeep the endpoint healthy; watch for deleted webhooksKeeps accepting deliveries, so the webhook isn't deleted
Choosing eventsSubscribe to charge/paid, not charge/success, and only to topics you processFilters and routes topics to the right service
TestingSend real topics to a public URL that forwards to localhostForwards to localhost and replays past events
Other limitsLog every delivery; reconcile against the APIStores 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:

  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.
  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

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.

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:

  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, 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:

  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 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:

  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 as fixtures.
  3. 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:

  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.

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.

Not affiliated with Recharge. Facts are compiled from public sources and linked inline.