Webhooks are global, not per user. You subscribe once and receive events for all
of your users. There’s no need to register a webhook per user, and you don’t pass a
user API key when managing webhooks. These are integrator endpoints, so they use your
integrator signing headers only.
Register an endpoint
Create a webhook by pointing it at an HTTPS URL on your backend and listing the events you want. Use"*" to subscribe to every current and future event.
Events
Subscribe to
"*" to receive all of these, including events added later.
Receiving a delivery
Spritz sends aPOST to your URL with a JSON body identifying what changed:
id is omitted for events whose subject is the user rather than a separate resource —
capabilities.updated is the case you are most likely to meet. Key your handler off
event and treat id as optional.
Every delivery also carries these headers:
Deduplicate on
eventId: store it with a unique constraint and skip any delivery whose
eventId you have already accepted. One resource can still produce several legitimate
events, each with its own eventId, so never deduplicate on id.
achDebitReturn.*, id is the public dr_... return ID. Fetch it with
GET /v1/integrator/ach-debit/returns/{id}. Then use its depositId and sourceId to
refresh the deposit and funding source.
For onramp.*, fetch the on-ramp. When its source contains a depositId, fetch
GET /v1/deposits/{depositId} with the user’s authorization. These generic resource
events keep your UI and local state current. Do not send ACH push notifications from
generic onramp.* or achDebitReturn.* events. A retry can produce the same current
state, so state comparison alone cannot identify one notification occurrence.
For payment.*, id is the off-ramp id — fetch GET /v1/off-ramps/{id} with the user’s
authorization (or your HMAC credentials acting for them). A typical off-ramp fires
payment.created and payment.updated when it’s created, payment.updated as it moves
through the rails, and payment.completed when fiat lands. There is no
payment.failed event — a failure arrives as payment.updated, so never infer state
from the event name; read the off-ramp’s status. You’ll also see account.updated
fire on the destination bank account as its state changes. For user-facing
notifications, prefer the offramp.* milestone events —
they carry copy-ready snapshots; use payment.* only to keep local state in sync.
Off-ramp milestone events
The sixofframp.* events are the notification contract for crypto-to-fiat: one event
per user-meaningful moment, each with an immutable snapshot taken at the transition. They
follow the same handling contract as achDebit.*: deduplicate on eventId, drop stale
sequence values, and use a durable inbox (see the
handler rules below).
eventIdis an opaque string that identifies one notification occurrence. It stays the same across delivery retries and replays. Don’t parse its format.- Each milestone fires at most once per off-ramp, so one off-ramp produces at most six events.
sequenceis per off-ramp. It starts at1and increases in the order the milestones occurred. Drop any event whosesequenceis not above the highest you’ve accepted for thatid.- Don’t treat a gap in
sequenceas a missed event. Milestones can be skipped; for example, a payout can reachcompletedwithout anofframp.inFlightevent. Use delivery history to recover a missed delivery. - A reissued payout is a new off-ramp with a new
id. It gets its ownofframp.confirmedevent, and itssequencerestarts at1.
offRamp.status uses the off-ramp status
values, so it can be canceled even though no milestone has that name.
The event and milestone pair is fixed.
quoteId links the off-ramp to its quote (null
for auto-ramp-address deposits, which have no quote). transaction carries the funding
transaction’s hash and explorer link once known. failureMessage is reserved for
public-safe failure copy and is currently always null — branch on the milestone, not
on absent detail.
The
onrampCredit.* family (depositDetected, completed, failed, reversed,
refunded) is the same contract for auto-ramp-account funding deposits — fiat in,
crypto out.ACH debit communication events
The fiveachDebit.* events are the push-notification contract. Unlike generic
resource events, each delivery contains an immutable milestone snapshot:
eventId is an opaque string that identifies one notification occurrence and stays
unchanged across delivery retries and replays. Don’t parse its format. sequence starts
at 1 and increases for each communication milestone on that deposit. Don’t treat a gap
in sequence as a missed event. Use delivery history
for recovery instead. achDebit.deliveryProgress can fire more than once per deposit,
once for each newly confirmed partial amount. Each one has its own eventId and
sequence. Deliveries are still at least once and can arrive out of order. id, deposit.id, and fundingSource.id are the same public IDs used by the
deposit and funding-source APIs.
Each achDebit.* payload is versioned and fully typed in the OpenAPI contract. These
fields are always present:
The event and milestone pair is fixed:
Your webhook handler must durably accept the event before returning
2xx:
- Begin a database transaction.
- Insert
eventIdinto a webhook inbox with a unique constraint. If it already exists, commit and return2xxwithout enqueueing another push. - Compare
sequencewith the highest accepted sequence forid. If it is lower or equal, record it as stale, commit, and return2xx. - Update the deposit’s highest sequence and insert one push-outbox row keyed by
eventIdin the same transaction. - Commit and return
2xx. A separate worker sends the push.
eventId
as the push provider’s idempotency or collapse key when the provider supports one.
Never mark an event accepted only in memory.
Use the immutable event snapshot for push copy. Refetch the deposit separately for the
current UI; a later state must not change the meaning of an earlier notification.
See ACH debit user experience for the exact copy.
Verifying signatures
Each delivery is signed so you can confirm it came from Spritz, wasn’t modified in transit, and isn’t an old request replayed. Set a webhook secret withPOST /v1/integrator/webhook-secret, then verify the Spritz-Signature header against
the raw request body. Always verify against the raw body, before parsing JSON.
To verify:
- Split the header on
,and readtand everyv1value. - Reject the request if
tis more than 300 seconds from your current time. - Compute HMAC-SHA256 of
`${t}.${rawBody}`with your secret. - Accept the request if your result matches any
v1value, using a constant-time comparison. Otherwise reject it with401.
- Spritz signs deliveries only after you set a secret. Until then, deliveries arrive
without signature headers, so set a secret before going live and reject any request
without
Spritz-Signature. - Every attempt is signed at send time with the secrets valid at that moment.
- Deduplicate on
eventIdas well. The timestamp limits how long a captured request can be replayed;eventIdstops a replay inside that window from being processed twice.
Rotating your secret
When you set a new secret, Spritz keeps your previous secret valid for 24 hours. ThePOST /v1/integrator/webhook-secret response tells you until when, in
previousSecretValidUntil. During that window, Spritz-Signature carries one v1 for
each secret, current first, so a receiver holding either secret can verify. Move your
receiver to the new secret before previousSecretValidUntil.
Spritz keeps only one previous secret. If you rotate again before
previousSecretValidUntil, the secret you just replaced becomes the previous one and
the older secret stops working immediately. Finish moving to a new secret before you
rotate again.
A new secret takes up to about 60 seconds to reach delivery workers. If two secret
updates for your integration overlap, the second returns 409 with
code: "WEBHOOK_SECRET_UPDATE_IN_PROGRESS" and retryable: true. Retry it after a short
delay.
Legacy Signature header
Spritz still sends the original Signature header so existing integrations keep
working. It is the lowercase hex HMAC-SHA256 of the raw body, keyed with your current
secret only. It has no timestamp, so it does not protect against replay, and during a
rotation it is signed only with the new secret. Use Spritz-Signature for new
integrations and move existing ones to it.
Retries and delivery outcomes
Return a2xx as soon as you have durably accepted the event. If your endpoint can’t
accept it, Spritz retries the delivery for about 24 hours.
Each delivery runs as a series of attempts:
- Within a series, Spritz makes up to three attempts a few seconds apart. Each
attempt times out after 5 seconds. Spritz honours a short
Retry-Afterheader within that window. - Between series, Spritz waits 30 seconds, 2 minutes, 10 minutes, 30 minutes,
1 hour, 2 hours, 4 hours, 8 hours, then 8 hours. After the last series fails, the
delivery is
failed.
Every retry sends the same body,
eventId, and Spritz-Delivery-Id to the webhook’s
current URL. If you delete the webhook, its pending deliveries stop and are marked
failed. Duplicates can still reach you, so handlers must stay idempotent.
Choose your response by outcome:
Respond within 5 seconds. Durably accepting an event means writing it to your inbox.
Do slow work, such as sending a push notification or calling another API, after you
respond.
Webhook configuration is cached by delivery workers and can take about 60 seconds to
propagate. Wait before using a newly registered endpoint or changed secret in a test.
Delivery history
Inspect deliveries withGET /v1/integrator/webhooks/deliveries. Results are newest
first and cursor-paginated. Each record is one delivery, updated as its attempts run.
Spritz retains each record and its exact payload for at least 30 days. Follow cursors
until no more records remain.
Read
error before interpreting responseStatus:
Redeliver a delivery
Send a past delivery again withPOST /v1/integrator/webhooks/deliveries/{deliveryId}/redeliver. Spritz sends the same
payload, eventId, and Spritz-Delivery-Id to the webhook’s current URL and starts
a fresh retry schedule. The response is the delivery record, now pending.
Redeliver after you fix a handler that returned
4xx, or after an outage longer than
the retry window. Because the eventId is unchanged, your inbox safely skips any
delivery you had already accepted.
Best practices
Respond fast, process later
Respond fast, process later
Write the event to your durable inbox, return
2xx, and do the rest of the work
asynchronously. Each attempt times out after 5 seconds, and a timeout triggers a
retry and duplicate processing.Make handlers idempotent
Make handlers idempotent
Retries and redeliveries mean the same payload can arrive more than once.
Deduplicate permanently on
eventId. The same resource can also produce several
legitimate events, each with its own eventId, so never deduplicate on id. Fetch
current state and make applying it safe to repeat. See
Idempotency.Don't rely on event order
Don't rely on event order
Events are dispatched concurrently and are not ordered.
onramp.completed can
arrive before onramp.created for the same on-ramp, and does so most often when the
two transitions happen close together.Don’t reorder resource events by occurredAt either. Key your handler off the
resource id, fetch current state from the API, and
make each handler safe to run regardless of what has already been processed for that
resource — including the case where the first event you ever see for a resource is
its last one.For achDebit.* communication events, atomically ignore a sequence that is not
greater than the highest sequence you already accepted for that deposit. This
prevents a delayed partial-delivery event from producing a push after full delivery.Treat events as triggers, not truth
Treat events as triggers, not truth
On receipt, fetch the current resource from the API to get authoritative state
rather than relying solely on the event body.
Reconcile after an outage
Reconcile after an outage
Webhooks are notifications, not your only record. Page through the relevant public
list endpoint after downtime. For linked-bank deposits, page through
GET /v1/deposits/; this endpoint is user-scoped, not integrator-scoped, so an
integrator-wide recovery must iterate your own user roster and authorize each
user’s read. For ACH returns, use
GET /v1/integrator/ach-debit/returns. Then check
GET /v1/integrator/webhooks/deliveries for failed deliveries and
redeliver them, especially achDebit.* communication
events. Run this reconciliation at least every 24 hours; delivery payloads are
guaranteed for 30 days. Do not synthesize a historical push from current resource
state.