Webhooks 路 RecurCrypto API

Webhook documentation for recurring crypto payments

Webhooks keep your backend aligned with subscription lifecycle activity. Use them to update access, internal account state, or support tooling whenever a subscription changes.

Event types

  • subscription.created
  • subscription.charged
  • subscription.payment_failed
  • subscription.cancel_at_period_end_set
  • subscription.cancelled
  • subscription.ended

Illustrative V4 webhook envelope

The sample follows the current nested data.subscription, data.merchant and data.plan structure. Values and addresses are placeholders, not a captured live payment. V5 multichain events are not live.

{
  "id": "evt_example_001",
  "type": "subscription.charged",
  "createdAt": "2026-10-13T18:00:00Z",
  "data": {
    "subscription": {
      "id": "subscription_db_id",
      "status": "ACTIVE",
      "effectiveStatus": "ACTIVE",
      "subscriberAddress": "0x...",
      "subscriptionIdOnchain": "101",
      "lastTxHash": "0x...",
      "nextPaymentOnchain": "2026-11-13T18:00:00Z"
    },
    "merchant": { "id": "merchant_db_id" },
    "plan": { "id": "plan_db_id", "token": "USDC" },
    "reason": null
  }
}

Verification and retry strategy

A webhook is a delivery mechanism, not the only source of truth. Acknowledge valid events quickly, process them idempotently, and retain the event identifier so a retry cannot apply the same entitlement change twice. Delivery is at least once, not exactly once: an HTTP 2xx confirms transport acceptance, not final blockchain settlement or processing by your application. A crashed worker can retry the same immutable event id, and terminal failures require manual reconciliation. If delivery is delayed or support needs to verify state, reconcile against the API and the corresponding on-chain identifiers rather than guessing from the last webhook received.

V5 offline webhook rehearsal: not delivery

The localhost-only V5 merchant simulator can record manual ACCEPTED_SIMULATED and REJECTED_SIMULATED outcomes for an immutable demo outbox event. Each event permits at most three attempts, deduplicated by a client-supplied idempotency key; an accepted rehearsal cannot be repeated as a new attempt. Its SHA-256 event digest detects changes to a restricted simulation envelope but is not an HMAC signature, blockchain proof, real webhook acknowledgment or payment receipt.

No HTTP request is dispatched to a merchant, no retry worker runs, and no funds or entitlements change. These local results cannot establish delivery or settlement. The future V5 multired USDC flows for Polygon, Base and Arbitrum remain simulation-only, with Free 0% effective during prelaunch, future 1% disabled pending fresh consent, and gas accounted for separately.

Verify webhook signatures before processing

The current delivery code sends x-recurpay-event-id, x-recurpay-timestamp (milliseconds) and x-recurpay-signature (sha256= followed by a hex HMAC-SHA256). Compute the HMAC using your merchant webhook secret over the exact bytes of timestamp.rawBody; compare signatures in constant time and reject stale timestamps according to your own replay window. Do not parse and reserialize JSON before signature verification. Store the event id with a unique constraint before changing an entitlement.

A valid signature authenticates delivery, not on-chain finality. Reconcile the subscription state independently before granting paid access, and never interpret a V5 simulated receipt as a production settlement. For setup and authenticated API reads, consult the quickstart and API reference.

Secure webhook delivery and operational recovery

RecurCrypto signs the original event bytes and retains a stable event identifier across retries. The local delivery implementation checks public HTTPS destinations, pins validated DNS addresses to the outbound TLS connection to reduce DNS-rebinding SSRF risk, and never follows redirects. A temporary 408, 425, 429 or 5xx can be retried; Retry-After may specify seconds or an HTTP date, bounded to 24 hours. These are local implementation guarantees pending PostgreSQL and integration validation, not a guarantee that a merchant has processed the event.

The authenticated merchant event timeline offers a read-only operational view with pagination and event-type filtering. It intentionally labels charge and lifecycle records as database observations, not definitive blockchain receipts. For API integrations, GET /api/v1/events exposes the corresponding merchant-scoped cursor interface. Neither view should automatically unlock paid access without independently verified settlement.

Implementation notes

  • Use the merchant dashboard settings page to store your webhook URL and secret.
  • Deduplicate by event id and make delivery idempotent in your backend.
  • Treat the chain as contractual truth; use webhook delivery to accelerate UX and internal system updates.
  • Reconciliation should preserve on-chain identifiers like subscription id, plan id, and transaction hash.