Webhooks

Webhooks push HTTP notifications to your server when key events happen: balance changes, redemptions, tier transitions, and more. Instead of polling the API for changes, you register a URL and Scrip delivers signed payloads the moment each event occurs.

Choose an endpoint

What you want	Where to send it
Register a URL	`POST /v1/webhook-endpoints`
Verify a delivery	Check `Scrip-Signature`
Pause, rotate, or archive	`PATCH`, `/rotate-secret`, or `DELETE`
Inspect health	`GET /v1/webhook-endpoints/delivery-stats`
Replay a delivery	`POST /v1/webhook-deliveries/{id}/resend`

Create an endpoint

Register a URL and specify which events you want to receive. Subscribe only to the types you handle. "enabled_events": ["*"] receives every type.

POST /v1/webhook-endpoints

{
  "url": "https://example.com/webhooks/scrip",
  "description": "Production receiver",
  "enabled_events": ["balance.credited", "redemption.completed"]
}

The response includes a secret starting with whsec_. Store it immediately. It cannot be retrieved later. You’ll use it to verify signatures.

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "url": "https://example.com/webhooks/scrip",
  "secret": "whsec_a1b2c3d4e5f6...",
  "enabled_events": ["balance.credited", "redemption.completed"],
  "status": "ACTIVE",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

URLs must use HTTPS with a publicly resolvable hostname. Private IPs, localhost, .local, and .internal domains are rejected.

Event types

Every event type is one of two kinds.

Movement and lifecycle events

A movement event announces one journal entry: balance.*, transfer.completed, and program.*. Every journal action has exactly one movement event. A participant or group balance changes only through movement events that name it, as the subject, as the counterparty, or as a transfer source or recipient. A handler that applies those events in order reconstructs every participant and group balance. Program wallet balances cannot be reconstructed from webhooks: issuance from a prefunded wallet, voids that return value to it, and settlement differences post to the wallet without an event naming it. Reconcile wallets from Get program balance or Get program statement. A lifecycle event announces a resource changing state: redemption.*, fulfillment_account.*, reward.*, participant.*, and event.*. It carries the resource id, its status where the resource has one, and the ids of related resources. It never carries a journal entry id; the matching movement event does.

Movement events

Event	What happened
`balance.credited`	Value was credited to `AVAILABLE`, `HELD`, or `DEFERRED` by a rule action, an API credit, or a settlement.
`balance.debited`	Value was debited by a rule action or an API debit.
`balance.held`	Value moved from `AVAILABLE` to `HELD`.
`balance.released`	Value moved from `HELD` back to `AVAILABLE`.
`balance.voided`	Provisional rewards in `HELD` were voided back to their source.
`balance.expired`	Lots expired and their value was forfeited to breakage.
`balance.matured`	Value moved from `DEFERRED` to `AVAILABLE` after `matures_at` passed.
`balance.redeemed`	Value was spent on a redemption, from `AVAILABLE` for an instant redemption or from `HELD` for a capture.
`balance.forfeited`	Value was forfeited to breakage by a forfeit request or a `FORFEIT` rule action.
`balance.reversed`	A reversal returned redeemed value to `AVAILABLE` or clawed an event’s award back.
`transfer.completed`	A transfer between participants or groups completed.
`program.funded`	A program wallet was funded.
`program.burned`	A program wallet’s balance was burned.

Lifecycle events

Event	What happened
`redemption.pending`	A redemption was authorized with value reserved in `HELD`.
`redemption.completed`	An instant redemption completed or a pending redemption was captured.
`redemption.failed`	A pending redemption failed or timed out.
`redemption.cancelled`	A pending redemption was cancelled.
`redemption.reversed`	A redemption was fully or partially reversed.
`redemption.fulfillment_succeeded`	A gift-card order succeeded and the redemption was captured.
`redemption.fulfillment_failed`	A gift-card order failed or its deadline passed, and the reserved value was released.
`fulfillment_account.funds_low`	A gift-card order is waiting for you to fund the fulfillment account.
`fulfillment_account.status_changed`	A fulfillment account changed status, for example to `ACTIVE`, `DISABLED`, or `REJECTED`.
`reward.status_changed`	A reward’s `status` changed, including automatic inventory transitions.
`participant.created`	A participant was created, by the API or by their first event. Fires once per participant.
`participant.tier_changed`	A tier level was upgraded, downgraded, or removed for a participant, group, or program.
`event.completed`	Event processing completed and its rules ran.
`event.failed`	Event processing or validation failed.
`event.reversed`	A completed event’s awards were reversed.

Authorization emits redemption.pending and balance.held. Capture emits redemption.completed and balance.redeemed with bucket: "HELD". An instant redemption emits redemption.completed and balance.redeemed with bucket: "AVAILABLE". Failure, timeout, and cancellation emit redemption.failed or redemption.cancelled, plus balance.released when live reserved value was released. If you maintain a participant or group balance mirror from webhooks, apply the movement events; the lifecycle events tell you why each one happened.

Reward status events

reward.status_changed fires when a reward’s status changes between DRAFT, ACTIVE, OUT_OF_STOCK, and ARCHIVED. PATCH /v1/programs/{programId}/rewards/{rewardId} emits it when status changes. Same-status writes and non-status field updates do not. Creating a reward does not emit it; use the create response. For UNIT_BASED rewards with max_total, authorization and instant redemption can move ACTIVE to OUT_OF_STOCK. Fail, cancel, timeout, and reversal can move OUT_OF_STOCK back to ACTIVE. Under async fulfillment that cycle can repeat. Treat OUT_OF_STOCK as live inventory state, not a terminal catalog state. See Rewards catalog.

Gift-card events

Use gift-card events to update your application when an order finishes. On redemption.fulfillment_succeeded, retrieve a claim link for the redemption and make it available to the participant. On redemption.fulfillment_failed, show the failed outcome and inspect failure_reason. If you receive fulfillment_account.funds_low, add funds to the account in the dashboard. Scrip retries the order automatically. This alert is sent once per fulfillment, even if several attempts encounter a low balance. fulfillment_account.status_changed tells you when the account’s status changes, for example when it becomes ACTIVE, is disabled, or needs to be reconnected. Check status_reason and act on the account in the dashboard. These events include the redemption and program IDs so you can find the purchase in your application. They do not include a claim link. See Gift cards for handling orders that finish after the initial request. For the data object each type delivers, see Event payloads.

Read the payload

Every delivery sends a JSON envelope:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "balance.credited",
  "api_version": "2026-10-07",
  "created_at": "2026-01-15T10:30:00Z",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "journal_entry_id": "...",
    "organization_id": "...",
    "program_id": "...",
    "participant_id": "...",
    "asset_id": "...",
    "amount": "100.00",
    "bucket": "AVAILABLE"
  }
}

Field	Description
`id`	Webhook event ID (UUID). Same across all endpoints receiving this event. Use it to detect duplicates.
`type`	The event type string.
`api_version`	The payload contract the `data` object follows. Currently `2026-10-07`. See Versioning.
`created_at`	When the event was created (RFC 3339).
`organization_id`	Organization that owns the event.
`data`	Event-specific payload.

Versioning

Adding a field to a payload never changes api_version, so ignore fields you do not recognize. A change that renames, removes, or retypes a field gets a new api_version date. The value is fixed when the event is created. A retried delivery keeps the value it was created with, so a delivery labeled with an older date carries that older contract’s shapes.

Verify a signature

Every delivery includes a Scrip-Signature header so you can verify it came from Scrip and wasn’t tampered with.

Header format

Scrip-Signature: t=1706090400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9

Component	Description
`t`	Unix timestamp (seconds) when the signature was generated
`v1`	Hex-encoded HMAC-SHA256 signature

Verification steps

Extract components

Parse the t and v1 values from the Scrip-Signature header.

Construct signed payload

Concatenate the timestamp, a literal dot, and the raw request body: {t}.{raw_body}

Compute expected signature

Calculate HMAC-SHA256(your_endpoint_secret, signed_payload) and hex-encode the result.

Compare signatures

Use constant-time comparison. Reject the request if they don’t match.

Check timestamp

Reject if abs(now - t) exceeds your tolerance. We recommend 5 minutes.

import hmac, hashlib, time

def verify_webhook(header, secret, body):
    # Parse header
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp = parts["t"]
    signature = parts["v1"]

    # Construct signed payload
    signed_payload = f"{timestamp}.{body}"

    # Compute expected signature
    expected = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    # Constant-time compare
    if not hmac.compare_digest(signature, expected):
        raise ValueError("Invalid signature")

    # Replay protection
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("Timestamp too old")

const crypto = require("crypto");

function verifyWebhook(header, secret, body) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=", 2))
  );
  const { t: timestamp, v1: signature } = parts;

  const signedPayload = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  const valid = crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );

  if (!valid) throw new Error("Invalid signature");
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300)
    throw new Error("Timestamp too old");
}

Retry policy

If your endpoint has a retryable failure such as a 5xx response, network error, or timeout, Scrip retries with exponential backoff:

Attempt	Delay	Cumulative
1	Immediate	0
2	5 min	5 min
3	10 min	15 min
4	20 min	35 min
5	40 min	1h 15m
6	80 min	2h 35m
7	160 min	5h 15m
8	320 min	10h 35m

After 8 attempts (~10.5 hours), the delivery is marked FAILED. You can manually resend any terminal delivery to send the event again.

Response handling

Your Response	Scrip’s Behavior
2xx	Marked `DELIVERED`
429 (rate limited)	Retried at the `Retry-After` time when provided, otherwise after 30 seconds; parsed `Retry-After` values are capped at 1 hour. Does not count toward the endpoint’s failure rate. The endpoint is paused until `rate_limited_until`, while new matching events can continue to queue.
4xx (except 429)	Marked `FAILED` immediately. No retry.
5xx	Retried on the backoff schedule
Network error / timeout	Retried on the backoff schedule

Return a 2xx quickly (within 30 seconds). Process the payload asynchronously if your handler needs more time. Scrip times out each attempt after 30 seconds.

Delivery error codes

Failed attempts include a stable error_code alongside the human-readable last_error. Use error_code for alerts and dashboards.

Error Code	Meaning
`consumer_response_timeout`	Your endpoint did not respond before the timeout
`connection_error`	Scrip could not connect to your endpoint
`tls_error`	TLS handshake or certificate validation failed
`consumer_4xx`	Your endpoint returned a non-429 4xx response
`consumer_5xx`	Your endpoint returned a 5xx response
`rate_limited`	Your endpoint returned 429 and is paused for backoff
`endpoint_disabled`	The endpoint was disabled and queued deliveries were failed out
`endpoint_archived`	The endpoint was archived and queued deliveries were failed out
`endpoint_auto_disabled`	The endpoint was auto-disabled because of sustained failures
`endpoint_backlog_exceeded`	The endpoint was auto-disabled because its backlog was sustained and non-draining
`endpoint_no_longer_active`	The endpoint was not active at delivery time
`marshal_error`	Scrip could not serialize the webhook payload

Manage an endpoint

Disable and re-enable

Temporarily stop deliveries without deleting the endpoint:

PATCH /v1/webhook-endpoints/{id}

{"status": "DISABLED"}

Disabling an endpoint immediately fails queued or in-flight deliveries for that endpoint with error_code: "endpoint_disabled". Set status back to ACTIVE to receive future matching events. Events that occurred while the endpoint was disabled are not retroactively delivered. If you disabled an endpoint temporarily and still want to deliver specific failed events, re-enable the endpoint and resend the terminal delivery records.

Rotate secret

If a secret is compromised, rotate it immediately:

POST /v1/webhook-endpoints/{id}/rotate-secret

The old secret is invalidated immediately. Update your verification code with the new secret before any in-flight deliveries arrive.

Delete

Deleting an endpoint archives it. It stops receiving deliveries and is removed from list results:

DELETE /v1/webhook-endpoints/{id}

Check endpoint health

Scrip monitors delivery health per endpoint. A bad destination can be paused temporarily, then auto-disabled if it keeps failing or stops draining its backlog.

Mechanism	Effect
Circuit breaker	Sustained failures pause delivery until `circuit_broken_until`
Rate-limit backoff	A 429 response pauses delivery until `rate_limited_until`
Failure auto-disable	Sustained failures after cooldown set the endpoint to `DISABLED` and fail queued deliveries
Backlog auto-disable	A sustained, non-draining backlog sets the endpoint to `DISABLED` and fails queued deliveries

Use delivery stats to see whether an endpoint is healthy, paused, disabled, or building a backlog:

GET /v1/webhook-endpoints/delivery-stats

Each row includes the 24-hour delivery rollup (success_24h, fail_24h, success_rate, degraded) plus current backlog and block fields: pending_count, oldest_pending_at, circuit_broken_until, rate_limited_until, blocked_reason, and blocked_until. To re-enable an endpoint after resolving the underlying issue:

PATCH /v1/webhook-endpoints/{id}

{"status": "ACTIVE"}

HTTP 429 responses do not count toward the failure-rate breaker. However, if rate limiting creates a sustained, non-draining backlog, Scrip can auto-disable the endpoint with error_code: "endpoint_backlog_exceeded". Re-enable the endpoint and resend any failed deliveries you still need.

Recover a delivery

List deliveries for an endpoint

GET /v1/webhook-endpoints/{id}/deliveries?status=FAILED

Inspect a delivery

The detail endpoint includes last_response_status, last_response_body (truncated to 4 KB), last_error, error_code, and resend_seq:

GET /v1/webhook-deliveries/{id}

Resend a delivery

Resend issues a new delivery of the same event to the same endpoint: a fresh delivery with its own id and an incremented resend_seq. The source delivery is left untouched, so you keep a complete history of every attempt.

POST /v1/webhook-deliveries/{id}/resend

The response is the newly created delivery (status PENDING), which you can poll like any other. Use resend to replay a webhook after fixing a bug in your handler, or to confirm your endpoint deduplicates correctly.

If a request fails

Signal	What to do
Source delivery is `DELIVERED` or `FAILED`	Resend creates a new delivery, returned as `PENDING`
Source delivery is `PENDING` or `SENDING`	`409 Conflict` (`not_resendable`). Wait for it to finish.
Endpoint is disabled or archived	`409 Conflict` (`endpoint_not_active`). Re-enable, then resend.
Consecutive failures or a growing backlog	Read delivery stats, fix the handler, re-enable, then resend.

Delivery guarantees

Webhook events are created with their domain operations. If the underlying transaction rolls back, no webhook is emitted. Each webhook event is recorded under an idempotency key, so a retried operation such as event reprocessing never produces a second event. The key is type:resource_id, where the resource is the one the event leads with: the journal entry for a movement event, the redemption for a redemption status event, the reversal for redemption.reversed and event.reversed, the fulfillment for the two fulfillment events and fulfillment_account.funds_low, the event for event.completed and event.failed, and the participant for participant.created. Three event types can fire more than once for the same resource, so their keys also name the transition.

Event	Key
`fulfillment_account.status_changed`	`fulfillment_account.status_changed:{fulfillment_account_id}:{status}:{updated_at}`
`reward.status_changed`	`reward.status_changed:{reward_id}:{status}:{updated_at}` when you change the status. `reward.status_changed:{redemption_id or reversal_id}:{status}` for an automatic inventory transition.
`participant.tier_changed`	`participant.tier_changed:{trigger}:{target_id}:{tier}:{level}`, where `{trigger}` identifies the event or counter write that caused the change, `{target_id}` is the participant, group, or program, and `{level}` is `null` when the tier was removed.

Delivery is at-least-once: a single event may be delivered more than once if your endpoint returns a 2xx but the acknowledgment is lost in transit. Design your handler to be idempotent using the envelope’s id field to detect duplicates.

Event processing

When events complete or fail, and what to poll.

Redemption lifecycle

redemption.pending, capture, and timeout events.

Testing

Replay deliveries against a development endpoint.

Getting Started

Foundations

Earning

Participant State

Ledger & Balances

Spending

Operations

Advanced

Reference

Choose an endpoint

Create an endpoint

Event types

Movement and lifecycle events

Movement events

Lifecycle events

Reward status events

Gift-card events

Read the payload

Versioning

Verify a signature

Header format

Verification steps

Retry policy

Response handling

Delivery error codes

Manage an endpoint

Disable and re-enable

Rotate secret

Delete

Check endpoint health

Recover a delivery

List deliveries for an endpoint

Inspect a delivery

Resend a delivery

If a request fails

Delivery guarantees

Event processing

Redemption lifecycle

Testing

​Choose an endpoint

​Create an endpoint

​Event types

​Movement and lifecycle events

​Movement events

​Lifecycle events

​Reward status events

​Gift-card events

​Read the payload

​Versioning

​Verify a signature

​Header format

​Verification steps

​Retry policy

​Response handling

​Delivery error codes

​Manage an endpoint

​Disable and re-enable

​Rotate secret

​Delete

​Check endpoint health

​Recover a delivery

​List deliveries for an endpoint

​Inspect a delivery

​Resend a delivery

​If a request fails

​Delivery guarantees

Event processing

Redemption lifecycle

Testing

Choose an endpoint

Create an endpoint

Event types

Movement and lifecycle events

Movement events

Lifecycle events

Reward status events

Gift-card events

Read the payload

Versioning

Verify a signature

Header format

Verification steps

Retry policy

Response handling

Delivery error codes

Manage an endpoint

Disable and re-enable

Rotate secret

Delete

Check endpoint health

Recover a delivery

List deliveries for an endpoint

Inspect a delivery

Resend a delivery

If a request fails

Delivery guarantees