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.

Creating an Endpoint

curl -X POST https://api.scrip.dev/v1/webhook-endpoints \
  -H "Authorization: Bearer $SCRIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
}

Use "enabled_events": ["*"] to subscribe to all event types.

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

Event Types

Event	Description
`balance.credited`	Balance increased via rule action, API credit, or refund
`balance.debited`	Balance decreased via rule action or API debit
`balance.expired`	Lots expired and auto-forfeited
`balance.held`	Balance moved from AVAILABLE to HELD
`balance.released`	Balance moved from HELD back to AVAILABLE
`balance.voided`	Provisionally issued HELD lots cancelled via void-hold
`redemption.pending`	Redemption authorized with value reserved in HELD
`redemption.completed`	Instant redemption completed or pending redemption captured
`redemption.failed`	Pending fulfillment failed or timed out
`redemption.cancelled`	Pending fulfillment was cancelled
`redemption.reversed`	Redemption fully or partially reversed
`reward.status_changed`	Reward `status` changed, including automatic inventory transitions
`transfer.completed`	Transfer between participants or groups completed
`event.completed`	Event processing completed successfully
`event.failed`	Event processing or validation failed
`event.reversed`	A completed event’s awards were reversed via the reversal endpoint
`participant.created`	Participant created, whether explicitly via the API or automatically by their first event. Fires once per participant.
`participant.tier_changed`	Tier level upgraded, downgraded, or removed
`program.funded`	Program wallet funded
`program.burned`	Program wallet balance burned

Redemption lifecycle events

Authorization emits redemption.pending. Capture emits redemption.completed; failure and timeout emit redemption.failed; and cancellation emits redemption.cancelled. Pending-redemption resolution payloads include status. Failure and cancellation include failure_reason when supplied, while an automatic timeout uses failure_reason: "expired". Instant completion keeps the create-time payload shape.

Successful capture emits no balance.* event. If you maintain a balance mirror from webhooks, reconcile it with participant balance and statement reads so the authorization’s balance.held value does not remain in HELD.

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.

Payload Format

Every delivery sends a JSON envelope:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "balance.credited",
  "api_version": "2026-03-01",
  "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.
`type`	The event type string.
`api_version`	API version at time of emission. Currently `2026-03-01`.
`created_at`	When the event was created (RFC 3339).
`organization_id`	Organization that owns the event.
`data`	Event-specific payload.

For the data object each event type delivers, see the event payloads reference.

Signature Verification

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.

Example (Python)

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")

Example (Node.js)

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. The worker enforces a 30-second timeout per delivery attempt.

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

Managing Endpoints

Disable and Re-enable

Temporarily stop deliveries without deleting the endpoint:

curl -X PATCH https://api.scrip.dev/v1/webhook-endpoints/{id} \
  -H "Authorization: Bearer $SCRIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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:

curl -X POST https://api.scrip.dev/v1/webhook-endpoints/{id}/rotate-secret \
  -H "Authorization: Bearer $SCRIP_API_KEY"

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:

curl -X DELETE https://api.scrip.dev/v1/webhook-endpoints/{id} \
  -H "Authorization: Bearer $SCRIP_API_KEY"

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:

curl https://api.scrip.dev/v1/webhook-endpoints/delivery-stats \
  -H "Authorization: Bearer $SCRIP_API_KEY"

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:

curl -X PATCH https://api.scrip.dev/v1/webhook-endpoints/{id} \
  -H "Authorization: Bearer $SCRIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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.

Debugging Deliveries

List Deliveries for an Endpoint

curl https://api.scrip.dev/v1/webhook-endpoints/{id}/deliveries?status=FAILED \
  -H "Authorization: Bearer $SCRIP_API_KEY"

Inspect a Delivery

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

curl https://api.scrip.dev/v1/webhook-deliveries/{id} \
  -H "Authorization: Bearer $SCRIP_API_KEY"

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.

curl -X POST https://api.scrip.dev/v1/webhook-deliveries/{id}/resend \
  -H "Authorization: Bearer $SCRIP_API_KEY"

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. Only terminal deliveries can be resent, and the endpoint must be active:

Condition	Response
Source delivery is `DELIVERED` or `FAILED`	New delivery created, returned as `PENDING`
Source delivery is `PENDING` or `SENDING`	`409 Conflict` (`not_resendable`)
Endpoint is disabled or archived	`409 Conflict` (`endpoint_not_active`)

Best Practices

Practice	Rationale
Verify signatures on every request	Prevents spoofed deliveries
Return 2xx quickly, process async	Avoids timeouts and unnecessary retries
Use `*` sparingly	Subscribe only to events you need to reduce noise
Handle duplicates idempotently	Network retries can deliver the same event more than once. Use `id` to deduplicate.
Monitor failed deliveries	Check delivery status periodically or alert on consecutive failures

Delivery Guarantees

Webhook events are created atomically with their domain operations. If the underlying transaction rolls back, no webhook is emitted. Retried domain operations (like event reprocessing) do not produce duplicate webhooks. 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.

Getting Started

Foundations

Earning

Participant State

Ledger & Balances

Spending

Operations

Advanced

Reference

Creating an Endpoint

Event Types

Redemption lifecycle events

Reward status events

Payload Format

Signature Verification

Header Format

Verification Steps

Example (Python)

Example (Node.js)

Retry Policy

Response Handling

Delivery Error Codes

Managing Endpoints

Disable and Re-enable

Rotate Secret

Delete

Endpoint Health

Debugging Deliveries

List Deliveries for an Endpoint

Inspect a Delivery

Resend a Delivery

Best Practices

Delivery Guarantees

​Creating an Endpoint

​Event Types

​Redemption lifecycle events

​Reward status events

​Payload Format

​Signature Verification

​Header Format

​Verification Steps

​Example (Python)

​Example (Node.js)

​Retry Policy

​Response Handling

​Delivery Error Codes

​Managing Endpoints

​Disable and Re-enable

​Rotate Secret

​Delete

​Endpoint Health

​Debugging Deliveries

​List Deliveries for an Endpoint

​Inspect a Delivery

​Resend a Delivery

​Best Practices

​Delivery Guarantees

Creating an Endpoint

Event Types

Redemption lifecycle events

Reward status events

Payload Format

Signature Verification

Header Format

Verification Steps

Example (Python)

Example (Node.js)

Retry Policy

Response Handling

Delivery Error Codes

Managing Endpoints

Disable and Re-enable

Rotate Secret

Delete

Endpoint Health

Debugging Deliveries

List Deliveries for an Endpoint

Inspect a Delivery

Resend a Delivery

Best Practices

Delivery Guarantees