Webhook verification
Verify Recur webhooks in your backend using @recur/sdk.
Webhook verification
Recur posts signed JSON to your configured webhook URL on every relevant event. Use verifyWebhookSignature and parseWebhookPayload from @recur/sdk to validate and handle incoming webhooks.
Signing details
| Header | Description |
|---|---|
X-Recur-Signature | sha256= + hex HMAC over "${timestamp}.${rawBody}" |
X-Recur-Timestamp | Unix seconds at dispatch time (rejected if more than 5 minutes skew) |
The HMAC key is the per-app webhook secret you configure in the Recur dashboard.
Express
Next.js (App Router)
Raw Node (http.IncomingMessage)
Events
| Event | Trigger |
|---|---|
subscription_created | Initial registration after on-chain initialize |
payment_success | Keeper pulled and confirmed a payment |
payment_failed | Keeper attempted but failed (insufficient funds, delegation exhausted) |
cancel_requested | Subscriber or merchant called request_cancel |
cancel_finalized | Paid period elapsed and the PDA was closed |
cancel_forced | Merchant called force_cancel |
delegation_revoked | Subscriber manually revoked SPL Token delegation |
platform_pro_activated | Platform pro subscription activated |
platform_pro_past_due | Platform pro payment overdue |
platform_pro_downgraded | Platform pro downgraded due to non-payment |
Recur retries failed deliveries at 1m, 5m, 30m, 2h, 12h. Your endpoint should respond 2xx within 5 seconds and dedupe on event.data.id.
Coming Soon: @recur/server — Framework-specific middleware adapters (verifyWebhookExpress, verifyWebhookNext, verifyWebhookNode) that wrap the SDK primitives above with automatic response handling. Until then, use verifyWebhookSignature and parseWebhookPayload from @recur/sdk directly as shown above.