recharge-webhooks

Recharge Webhooks

When to Use This Skill

• How do I receive Recharge webhooks?
• How do I verify Recharge webhook signatures?
• Why is my X-Recharge-Webhook-Signature or X-Recharge-Hmac-Sha256 verification failing?
• How do I handle charge/paid, charge/failed, or subscription/cancelled events?
• How do I create a Recharge webhook subscription via the API?

Verification (core)

Every webhook delivery includes two signature schemes: a recommended timestamp-bound scheme (use this for all new integrations) and a legacy body-only scheme that remains supported.

Recommended: timestamp-bound scheme

Two headers are sent:

• X-Recharge-Webhook-Timestamp — Unix epoch seconds (integer) at the time the request was signed.
• X-Recharge-Webhook-Signature — comma-separated key/value pairs in the form t=<epoch>,v1=<hex> (future schemes may add v2=…, so parse by key).

To verify:

1. Parse t and v1 from X-Recharge-Webhook-Signature (t matches the timestamp header).
2. Reject if abs(now - t) > 172800 seconds (48 hours) — replay protection.
3. Compute HMAC-SHA-256, keyed by the API Client Secret, over "<timestamp>.<payload_json>" — the timestamp, a literal dot, then the exact raw JSON bytes as transmitted (re-serializing breaks it).
4. Compare the hex digest to v1 with a constant-time comparison.

Node:

const crypto = require('crypto');

function verifyRechargeWebhookTimestamped(rawBody, signatureHeader, clientSecret) {
  if (!signatureHeader) return false;
  // Parse `t=<epoch>,v1=<hex>` by key.
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((pair) => pair.split('=').map((s) => s.trim()))
  );
  const timestamp = parseInt(parts.t, 10);
  if (!Number.isFinite(timestamp) || !parts.v1) return false;
  // Reject deliveries outside the 48-hour window.
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 172800) return false;
  // HMAC-SHA-256 over "<timestamp>.<raw body>", keyed by the client secret.
  const digest = crypto
    .createHmac('sha256', clientSecret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(parts.v1));
  } catch {
    return false; // length mismatch = invalid
  }
}