Webhooks

Quarzo Life uses webhooks to push real-time notifications to your server whenever an event occurs — a policy is created, a payment is processed, a subscriber is updated, and so on.

Each event delivers the full object payload, so you never need to make a follow-up API call to fetch the current state of the resource.

Registering an endpoint

In the dashboard, navigate to Settings → Webhooks and add your HTTPS endpoint URL. Quarzo Life will immediately start sending events to it.

All events

This version of the API does not support event filtering. Your endpoint will receive every event type. Selective delivery will be available in a future release.

Event structure

Every webhook request is a POST with a JSON body. All events share the same envelope:

{
  "id": "evt_01J3K9Z2XQ4R8T5V6W7Y0A1B2C",
  "type": "transfer.succeed",
  "created_at": "2026-07-06T14:32:00Z",
  "data": {
    "id": "trf_01J3K9Z2XQ4R8T5V6W7Y0A1B2C",
    "status": "pending",
    "amount": 125000,
    "currency": "EUR"
    // ... full object
  }
}

Field	Description
id	Unique identifier for this event delivery.
type	Dot-separated event name, e.g. transfer.created.
created_at	ISO 8601 timestamp of when the event was generated.
data	The full resource object at the time of the event.

Responding to events

Your endpoint must return a 2XX status code within 10 seconds to acknowledge receipt. Any other response — or no response — is treated as a failure and will trigger a retry.

HTTP/1.1 200 OK

Process the event asynchronously if your handler needs more time. Acknowledge immediately, then do the work in the background.

Idempotency

Your endpoint may receive the same event more than once. Use the id field to deduplicate deliveries and make your handler idempotent.

Retry policy

If a delivery attempt fails, Quarzo retries with exponential backoff. The delay between attempts grows with each retry, with a small random jitter added to prevent thundering-herd effects:

delay(n) = (5400s × 2^n) + random(0, 60s)

Attempt	Base delay	Approximate time after first failure
1st retry	5 400 s	~1 h 30 min
2nd retry	10 800 s	~4 h 30 min
3rd retry	21 600 s	~10 h 30 min
4th retry	43 200 s	~22 h 30 min
5th retry	—	within 24 h of first failure

After 5 failed retries, the delivery is abandoned. Make sure your endpoint is reliable and returns 2XX promptly.

Resuming after failures

The ability to manually replay failed events from the dashboard is on the roadmap and will be available in a future release.

Security

Quarzo signs every webhook payload so you can verify it came from us. Each request includes a signature header:

X-Quarzo-Signature: t=1720275120,v1=abc123...

Verify the signature before processing the event:

1. Extract the timestamp t and the signature v1 from the header.
2. Concatenate the timestamp, a ., and the raw request body: {t}.{body}.
3. Compute HMAC-SHA256 of that string using your webhook secret.
4. Compare your result to v1. Reject the request if they do not match.
5. Reject the request if the timestamp is more than 5 minutes in the past, to prevent replay attacks.

Your webhook secret is available in the dashboard under Settings → Webhooks.

Best practices

• Respond fast, process async. Return 200 immediately and handle the event in a background job.
• Deduplicate on id. Store processed event IDs to safely handle duplicate deliveries.
• Always verify the signature. Never process a payload without checking X-Quarzo-Signature.
• Monitor your endpoint. Failed deliveries are visible in Settings → Webhooks → Delivery logs.