Skip to main content

​
What webhooks do

Webhooks push billing events to your server as they happen — subscription created, payment succeeded/failed, invoice finalized, and more — so your app reacts in real time instead of polling.
Full event catalog and payload shapes: Webhooks.

​
Prerequisites

  • An API key for the API call below, or dashboard access to Developers.
  • A public HTTPS endpoint on your server to receive deliveries.

​
Step 1: Register your endpoint

The Webhooks tab in Developer settings

Webhooks — endpoints, their subscribed events, and delivery status

Point Recurso at a public HTTPS URL and subscribe to the events you care about. In the dashboard, go to Developers → Webhooks → Add endpoint; or via the API:
You’ll get back a signing secret — store it; you need it to verify deliveries.

​
Step 2: Verify the signature

Every delivery is signed with your endpoint’s secret. On receipt, recompute the signature over the raw body and compare — reject anything that doesn’t match, so only genuine Recurso events are trusted. The exact scheme is in Verify signature.
Verify against the raw request body, before any JSON parsing/re-serialization — reformatting the bytes breaks the signature.

​
Step 3: Respond fast and handle retries

Return 2xx quickly (do heavy work asynchronously). If your endpoint errors or times out, Recurso retries with backoff; make your handler idempotent (dedupe on the event id) so a redelivery is harmless.

​
Verify your setup

1

The endpoint is registered

It appears under Developers → Webhooks with its subscribed event types.
2

A test event is signed and accepted

Send a test event; your handler verifies the signature and returns 2xx.
3

Deliveries are tracked

Successful and failed deliveries show in the endpoint’s delivery log; you can redeliver a past event.

​
Next steps