This page explains the concepts. To turn it on step by step, follow the webhooks setup guide.
Event Notifications
Webhooks notify your application when events happen in Recurso:- Subscription changes
- Payment events
- Invoice updates
- Customer actions
Register a Webhook
Event Payload
Verify Signature
Always verify webhook signatures:Event Types
Recurso emits exactly these ten event types:Subscription Events
Payment Events
Invoice Events
Customer Events
Pauses, refunds, and disputes are visible on their resources (and in the
Events feed) but do not have dedicated
webhook types today — subscribe to the list above only.
Retry Policy
Failed deliveries are retried with exponential backoff:2^attempt × 30s, capped at 24 hours between attempts. Any non-2xx response (or a transport error) counts as a failure.
After 5 attempts the delivery becomes terminal: it is marked failed with the last HTTP status code and error body recorded, and the worker stops retrying it. Terminal deliveries are never picked up again automatically — use redelivery to start a fresh cycle.
Delivery Tracking & Redelivery
Every delivery attempt is recorded per event × endpoint. Each record carries a derived status:Inspect deliveries
Per endpoint (the delivery log for one receiver, with status filter and pagination):Redeliver an event
Redelivery resets the event’s delivery records topending — attempt counter cleared, fresh retry cycle — for every active endpoint subscribed to the event’s type, and returns 202 immediately (the worker delivers on its next poll):
deliveries_queued: 0 when nothing subscribes). Because your receiver may see the same event ID more than once, keep webhook handlers idempotent.
Test Webhooks
Send test events to verify your integration:Best Practices
Return 200 Quickly
Acknowledge receipt immediately, process async
Handle Duplicates
Use event IDs for idempotency
Verify Signatures
Always validate webhook signatures
Log Everything
Log events for debugging