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

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

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Recharge's official docs](https://docs.getrecharge.com/docs/webhooks-overview).

[Overview](https://hookdeck.com/webhooks/recharge) · [Webhook events (62)](https://hookdeck.com/webhooks/recharge/events) · [MCP events](https://hookdeck.com/webhooks/recharge/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/recharge/verify) · [Production guide](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/recharge/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Recharge-Webhook-Signature` Format: t=<epoch>,v1=<hex> | [Recharge docs](https://developer.rechargepayments.com/v2/webhooks_validation) |
| Scheme | `HMAC-SHA256` | [Recharge docs](https://developer.rechargepayments.com/v2/webhooks_validation) |
| Signed material | `{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. | [Recharge docs](https://developer.rechargepayments.com/v2/webhooks_validation) |
| Body format | `JSON` Content type: application/json. | [webhook-skills](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/recharge-webhooks/SKILL.md) |
| API versioning | `X-Recharge-Version header` | [webhook-skills](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/recharge-webhooks/SKILL.md) |
| Send timestamp | `X-Recharge-Webhook-Timestamp` Reject deliveries older than 48 hours. | [Recharge docs](https://developer.rechargepayments.com/v2/webhooks_validation) |
| Legacy signature | `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. | [Recharge docs](https://developer.rechargepayments.com/v2/webhooks_validation) |
| Envelope | `charge` | [Recharge docs](https://docs.getrecharge.com/docs/webhooks-overview) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill recharge-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/recharge/skill) |
| Not yet known | how events are identified | [Help fill this in](https://hookdeck.com/contact) |

[Verify Recharge webhooks](https://hookdeck.com/webhooks/recharge/verify)

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

## Setting up Recharge webhooks

- Create a webhook with `POST https://api.rechargeapps.com/webhooks`, sending an `address` and a `topic`.
- Subscribe only to the topics you process, and create one webhook per topic.

## Delivery behaviour

- **Timeout:** 5 s to respond 200. acknowledge fast, process asynchronously. [Guide](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#timeouts)
- **Retries:** 20 over 48 hours. triggered by no response, 408, 429 or 5xx. [Guide](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#retries)
- **After retries run out:** webhook deleted. Recharge sends nothing more until you recreate it. [Guide](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#retries)
- **Duplicates:** possible. across the 48-hour retry window; dedupe on a payload id. [Guide](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#duplicates)

## Known failure modes

1. **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](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#retries)
2. **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](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#duplicates)
3. **Subscribing to a topic that doesn't exist.** The paid-charge topic is `charge/paid`; there's no `charge/success`. Check topic names against the events list before you subscribe. [Choosing Recharge topics](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#choosing-events)
4. **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](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#other-limits)

From [Hookdeck's Recharge guide](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts).

## Recharge webhook best practices

- **[Verify the timestamp-bound signature](https://hookdeck.com/webhooks/recharge/verify).** Check X-Recharge-Webhook-Signature in new integrations. The legacy header has no timestamp, so it gives no replay protection.
- **[Acknowledge within 5 seconds](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts#duplicates).** 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](https://hookdeck.com/webhooks/recharge/events#subscription%2Fcreated): A subscription is created
- [subscription/cancelled](https://hookdeck.com/webhooks/recharge/events#subscription%2Fcancelled): A subscription is cancelled

### Charges

- [charge/created](https://hookdeck.com/webhooks/recharge/events#charge%2Fcreated): A charge is queued for an upcoming order
- [charge/paid](https://hookdeck.com/webhooks/recharge/events#charge%2Fpaid): A charge is successfully paid
- [charge/failed](https://hookdeck.com/webhooks/recharge/events#charge%2Ffailed): A charge attempt fails

### Orders

- [order/created](https://hookdeck.com/webhooks/recharge/events#order%2Fcreated): An order is created
- [order/processed](https://hookdeck.com/webhooks/recharge/events#order%2Fprocessed): An order is processed

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [subscription](https://hookdeck.com/webhooks/recharge/events#resource-subscription) | 10 | 7 |
| [charge](https://hookdeck.com/webhooks/recharge/events#resource-charge) | 9 | 7 |
| [order](https://hookdeck.com/webhooks/recharge/events#resource-order) | 9 | 5 |
| [customer](https://hookdeck.com/webhooks/recharge/events#resource-customer) | 6 | 1 |
| [checkout](https://hookdeck.com/webhooks/recharge/events#resource-checkout) | 4 | 2 |
| [address](https://hookdeck.com/webhooks/recharge/events#resource-address) | 3 | 2 |
| [bundle_selection](https://hookdeck.com/webhooks/recharge/events#resource-bundle-selection) | 3 | 0 |
| [onetime](https://hookdeck.com/webhooks/recharge/events#resource-onetime) | 3 | 3 |
| [payment_method](https://hookdeck.com/webhooks/recharge/events#resource-payment-method) | 3 | 0 |
| [plan](https://hookdeck.com/webhooks/recharge/events#resource-plan) | 3 | 0 |

2 more resources. [All 62 events](https://hookdeck.com/webhooks/recharge/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/recharge/events): Every covered Recharge event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/recharge/mcp-events): How an agent subscribes to Recharge events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/recharge/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/recharge/guide-duplicates-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/recharge/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill recharge-webhooks`
---

Not affiliated with Recharge. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/recharge.json) · [Report a correction](https://hookdeck.com/contact)
