Skip to main content
Money movement is asynchronous. An off-ramp is requested, then converts, then settles to a bank account over time. Webhooks let Spritz notify your backend the moment something changes, so you don’t have to poll. Webhooks are configured per integrator, so you manage them with your integrator credentials (HMAC). See Authentication.
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.
You can list, update, and delete webhooks too:

Events

Subscribe to "*" to receive all of these, including events added later.

Receiving a delivery

Spritz sends a POST 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.
The body tells you which resource changed, not its full state. Treat it as a trigger: fetch the resource from the API to get authoritative state before acting on it. For 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 six offramp.* 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).
Event identity:
  • eventId is 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.
  • sequence is per off-ramp. It starts at 1 and increases in the order the milestones occurred. Drop any event whose sequence is not above the highest you’ve accepted for that id.
  • Don’t treat a gap in sequence as a missed event. Milestones can be skipped; for example, a payout can reach completed without an offramp.inFlight event. Use delivery history to recover a missed delivery.
  • A reissued payout is a new off-ramp with a new id. It gets its own offramp.confirmed event, and its sequence restarts at 1.
Payload fields: 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 five achDebit.* 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:
  1. Begin a database transaction.
  2. Insert eventId into a webhook inbox with a unique constraint. If it already exists, commit and return 2xx without enqueueing another push.
  3. Compare sequence with the highest accepted sequence for id. If it is lower or equal, record it as stale, commit, and return 2xx.
  4. Update the deposit’s highest sequence and insert one push-outbox row keyed by eventId in the same transaction.
  5. Commit and return 2xx. A separate worker sends the push.
This is a small generic inbox/outbox, not ACH-specific state inference. Use eventId as the push provider’s idempotency or collapse key when the provider supports one. Never mark an event accepted only in memory.
HTTP delivery cannot guarantee that an external push provider displays a message exactly once. The stable event ID, sequence guard, transactional push outbox, and provider idempotency key close every duplicate path your integration can control.
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 with POST /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:
  1. Split the header on , and read t and every v1 value.
  2. Reject the request if t is more than 300 seconds from your current time.
  3. Compute HMAC-SHA256 of `${t}.${rawBody}` with your secret.
  4. Accept the request if your result matches any v1 value, using a constant-time comparison. Otherwise reject it with 401.
  • 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 eventId as well. The timestamp limits how long a captured request can be replayed; eventId stops 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. The POST /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 a 2xx 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-After header 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 with GET /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 with POST /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

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.
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.
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.
On receipt, fetch the current resource from the API to get authoritative state rather than relying solely on the event body.
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.