Skip to main content
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):
Per event (did every endpoint receive event X?):

Redeliver an event

Redelivery resets the event’s delivery records to pending — 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):
Redelivery is idempotent: repeated calls reset the same records rather than creating duplicates. Inactive endpoints are skipped (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