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.

62 events covered

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

Signature header
X-Recharge-Webhook-Signature

Format: t=<epoch>,v1=<hex>

Scheme
HMAC-SHA256
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.

Body format
JSON

Content type: application/json.

API versioning
X-Recharge-Version header
Send timestamp
X-Recharge-Webhook-Timestamp

Reject deliveries older than 48 hours.

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.

Envelope
charge
Agent skill
npx skills add hookdeck/webhook-skills --skill recharge-webhooks
Not yet known

How events are identified

Not in the registry yet.

Verify Recharge webhooks →

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

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

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

subscription/created · /updated · /cancelled · /activated +6

10 7
charge

charge/created · /paid · /failed · /max_retries_reached +5

9 7
order

order/created · /processed · /deleted · /updated +5

9 5
customer

customer/created · /updated · /activated · /deactivated +2

6 1
checkout

checkout/created · /updated · /processed · /completed

4 2
address

address/updated · /created · /deleted

3 2
bundle_selection

bundle_selection/created · /deleted · /updated

3 0
onetime

onetime/created · /updated · /deleted

3 3
payment_method

payment_method/created · /deleted · /updated

3 0
plan

plan/created · /deleted · /updated

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.

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