Receive webhook events

Webhooks let your system react to events on your SUQO account without polling. When something happens — a checkout succeeds or fails, a subscription changes status — SUQO sends a signed HTTP POST to a URL you control.

Registering and managing endpoints is done in the dashboard: see Webhooks in the user guide. This page covers what your endpoint has to do; Webhook events covers the payloads.

How it works

Event on your SUQO account
        │
        ▼
SUQO signs the JSON payload with your account signing secret
        │
        ▼
POST → your endpoint URL          (10s timeout)
        │
        ├─ you reply 2xx  → done
        └─ anything else  → retried up to 5 times, 60s apart
                             └─ still failing → we email your account address

You register one endpoint URL per event type, and your account has one signing secret that signs every webhook we send you. Both are managed from the SUQO dashboard, where you can also copy the secret and fire a test delivery to your endpoint.

What your endpoint must do

• Be publicly reachable over HTTPS
• Accept POST with a JSON body
• Return a 2xx within 10 seconds — acknowledge first, process asynchronously
• Verify the signature before trusting the payload — see Verify a webhook signature

Retries

A delivery counts as successful only if you return 2xx. Any other status, a connection error, or a response slower than 10 seconds is a failure and is retried — up to 5 attempts, 60 seconds apart. After that we stop and email your account's registered email address. Those events are not re-delivered later.

Failure emails are throttled to at most one per 24 hours per webhook, so a permanently-dead endpoint nags you daily rather than on every event.

Because deliveries are retried independently, they are not ordered: a later transition can land before an earlier one. Treat subscription_id + changed_at as the idempotency key so a retry of a delivery you already handled is a no-op.

Test deliveries

A test fired from the dashboard is a real, fully-signed delivery to your endpoint, with the body:

{ "event": "checkout.succeeded", "data": { "test": true } }

Note the shape differs from a live event — the fields sit under data. Use it to confirm signature verification and reachability, not to exercise your payload parsing.