Recharge webhooks
Recharge webhooks are HTTP POSTs sent to an address you register, each carrying a JSON payload about a subscription, charge or order event.
How Recharge webhooks work
If you're provisioning access, syncing subscription state or triggering fulfillment off Recharge, webhooks are how you react without polling the API. You create them through the Recharge Admin API, subscribing each one to a single topic. Topics are slash-separated and scoped by resource, such as charge/paid or subscription/created.
When a topic fires, Recharge sends the payload to the address you registered and expects a 200 within 5 seconds. API versions 2021-01 and 2021-11 share the same token and topic names.
Key facts
{t}.{raw body} t from the signature header (equal to X-Recharge-Webhook-Timestamp), a literal dot, then the body bytes exactly as sent. Re-serialised JSON fails.
X-Recharge-Hmac-Sha256 hex(SHA-256(API Client Secret + raw body)), a plain keyed digest, secret first, not an HMAC despite the header name.
Setting up Recharge webhooks
- Create a webhook with
POST https://api.rechargeapps.com/webhooks, sending anaddressand atopic. - Subscribe only to the topics you process, and create one webhook per topic.
Delivery behaviour
Known failure modes
From Hookdeck's Recharge guide →-
A failing endpoint loses its webhook
After 20 failed retries over 48 hours, Recharge deletes the webhook and sends nothing more until you recreate it. Watch for failures, and check your webhooks still exist.
Retries and deleted webhooks → -
Duplicates across the retry window
Recharge can deliver an event more than once across its 48-hour retry window. Dedupe on a payload identifier and make side effects idempotent.
Duplicate deliveries and idempotency → -
Subscribing to a topic that doesn't exist
The paid-charge topic is
Choosing Recharge topics →charge/paid; there's nocharge/success. Check topic names against the events list before you subscribe. -
Missed events can't be recovered
Recharge has no replayable delivery log. Log every delivery yourself and reconcile against the API.
Recover after retries are exhausted →
Recharge webhook best practices
- Verify the timestamp-bound signature. Check X-Recharge-Webhook-Signature in new integrations. The legacy header has no timestamp, so it gives no replay protection.
- Acknowledge within 5 seconds. Return a 200 and move the work to a queue, so slow processing doesn't count towards the failures that delete your webhook.
- Dedupe and reconcile. Dedupe on a payload identifier, make side effects idempotent, and reconcile against the API for anything you can't afford to miss.
Common Recharge webhook events
Subscriptions
subscription/created | A subscription is created |
subscription/cancelled | A subscription is cancelled |
Charges
charge/created | A charge is queued for an upcoming order |
charge/paid | A charge is successfully paid |
charge/failed | A charge attempt fails |
Orders
order/created | An order is created |
order/processed | An order is processed |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
subscription | 10 | 7 |
charge | 9 | 7 |
order | 9 | 5 |
customer | 6 | 1 |
checkout | 4 | 2 |
address | 3 | 2 |
bundle_selection | 3 | 0 |
onetime | 3 | 3 |
payment_method | 3 | 0 |
plan | 3 | 0 |
2 more resources, including Other Recharge events. All 62 events →
In this hub
| Webhook events → | Every covered Recharge event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Recharge events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill recharge-webhooks |
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.