Skip to main content
A webhook is an HTTP POST we send to a URL you own when something happens to your processor — a paid sale, a failed run. You register one URL per processor, we sign every call so you can prove it came from us, and we keep retrying until your endpoint answers. One webhook per processor. Register it in My Processors → Webhooks, or over the API.

​
Register, and prove you own the endpoint

When you save a URL we immediately send it a one-time verification POST. Your endpoint must answer 2xx. Only then does the webhook activate. This step is not paperwork. A wallet signature proves you asked for the webhook; it does not prove the target agreed to receive our calls. The verification ping is what stops anyone pointing us at a stranger’s server. Until your endpoint answers it, the webhook is registered but inactive and delivers nothing.
The URL must be https on port 443, a real hostname (no IP addresses), and not one of our own domains. Redirects are not followed — a redirect is a second URL nobody verified.
On success you are shown a signing secret exactly once (whsec_…). Save it now — it is never shown again. Registering again mints a new one, and is also how you re-verify after a change.

​
What you receive

Three event types, each a JSON body: The payload carries the run’s identity and outcome — never the caller’s input or output, which are their data, not yours:

​
Verify the signature

Every delivery carries an X-SGL-Signature header in Stripe’s format:
v1 is hmac-sha256(secret, "{t}.{rawBody}"). Recompute it over the raw request body and reject anything that does not match — an unsigned or wrongly-signed call is not from us. The t timestamp is inside the signed string, so you can also reject anything too old to be a genuine, timely event.
Also present: X-SGL-Event (the type) and X-SGL-Delivery (the delivery id — use it to dedupe, since a retried delivery reuses it).

​
Retries, and auto-disable

Answer 2xx fast — we time out a delivery after 10 seconds. If your endpoint is down or slow, we retry with backoff — roughly 1 minute, then 5, 15, an hour, and on out to a day, eight attempts in all. Do the slow work after you have acknowledged; a webhook handler that blocks on your own processing is a webhook handler that times out. After 20 consecutive failed deliveries the webhook auto-disables so we never hammer a dead endpoint. Re-register (which re-verifies) to turn it back on. A delivery older than about a day is dropped unsent rather than arriving stale.
Events are derived from your sales, not emitted from the payment path, so a webhook problem can only ever delay a notification — it can never affect a buyer’s payment or your runs.

​
Test it

The Send test ping button (or POST /processors/{slug}/webhook/test) delivers a test.ping event through the real signing-and-delivery path, and tells you exactly what your endpoint answered. Use it to confirm your signature check before a real sale depends on it.

​
From code

Registration and deletion are owner mutations, so each needs a fresh Solana wallet signature, the same as every other change to your processor.