LoyumiDeveloper docsOpen Sandbox
RUN IT SAFELY

Launch, observe, reconcile, and recover.

Use production gates, retry rules, signed webhooks, reconciliation checks, and incident runbooks built for loyalty liabilities.

Developer docs · no accountSandbox firstAPI 1.13.0 · 121 operations · 106 paths
GO-LIVE GATE

Production is a controlled change.

○
Program

Economics approved; rewards, caps, expiration, and pending policy reviewed.

○
Identity

Customer mapping, consent status, duplicates, and deletion process tested.

○
Commerce

Earn, retry, full return, partial return, and out-of-order behavior proven.

○
Finance

Opening balances and liability control totals reconciled with signed approval.

○
Security

Least-privilege production keys stored, rotated, and monitored server-side.

○
Operations

Alerts, owners, webhook replay, rollback, and customer support scripts ready.

AUTOMATIC MAINTENANCE · SOURCE CONTROL

Quiet programs still need expiration, retry, and cleanup work.

The checked-in worker asks for a bounded maintenance sweep every minute and after normal API traffic. D1 grants a durable per-environment lease so overlapping workers do not own the same sweep.

  1. 1

    Set a dedicated secret

    MAINTENANCE_SECRET is required, server-only, at least 32 characters, non-placeholder, and separate from every public API or privacy key. Without it, the worker safely does no maintenance work.

  2. 2

    Trigger two ways

    The source config declares * * * * *; ordinary API traffic also schedules the same sweep asynchronously. These paths may overlap.

  3. 3

    Lease, page, then resume

    D1 chooses at most four due environments per sweep. Each environment gets a fresh owner token and a three-minute heartbeat lease, processes one bounded keyset page, and stores its phase and cursor. Every write is fenced by that token. Remaining cycle work becomes eligible after one second; a completed idle cycle waits one minute.

  4. 4

    Inspect evidence

    The lease stores last start, last successful completion, bounded last error, and resumable checkpoint. Operators still need external alerts and a deployment-specific runbook.

IMPLEMENTED IN SOURCE

Bounded leased sweep

  • Per-minute scheduled trigger
  • API-traffic-triggered sweep
  • D1 per-environment lease
  • Reservation and point expiry, webhook retry, and cleanup dispatch
NOT PROVEN PUBLICLY

Operating reliability

  • Deployed cron uptime
  • External monitoring and paging
  • Maximum processing or delivery time
  • Contractual SLA, RPO/RTO, restore, or DR evidence
SIGNED OUTCOMES

Verify the bytes before trusting the event.

Loyumi deliveries use x-loyumi-event-id, x-loyumi-timestamp, and x-loyumi-signature: v1=<hex>. Existing integrations may continue reading the legacy x-loyaltyos-* aliases during the compatibility window.

  1. 1

    Read the raw body

    Do not parse and re-serialize before verification.

  2. 2

    Reject stale timestamps

    Apply a short replay window that matches your risk policy and tolerate normal clock skew.

  3. 3

    Compute the expected signature

    HMAC-SHA256 the UTF-8 string timestamp.raw_body with the endpoint secret.

  4. 4

    Compare in constant time

    Only enqueue trusted events. Deduplicate by event ID and respond quickly.

Signature input
expected = HMAC_SHA256(
  endpoint_secret,
  x_loyumi_timestamp + "." + raw_request_body
)

constant_time_compare("v1=" + hex(expected), x_loyumi_signature)
RETRY POLICY

Retry transport failures, not business decisions.

Timeout / connection failureRetry with exponential backoff, the same idempotency key, and the identical body.
429Honor Retry-After; keep the same key and body.
5xxRetry with jitter and a cap; retain requestId.
400 / 413 / 415 / 422Fix the request. Do not retry unchanged.
401 / 403Repair credential, environment, or scope before retrying.
404 / 409Resolve resource or policy state; do not hide it with blind retries.
FINANCIAL CONTROL

Compare three independent views.

1Commerce facts

Completed and returned order value by source reference.

2Loyalty ledger

Issued, clawed back, expired, redeemed, pending, and available points.

3Finance control

Opening, movement, closing liability, and documented adjustments.

INCIDENT RUNBOOK

Contain first. Preserve evidence. Recover deliberately.

0–15 min
Contain

Disable the affected key, endpoint, campaign, or production path without deleting evidence.

15–30 min
Measure

Bound environments, programs, members, source references, point value, and customer impact.

30–60 min
Decide

Assign incident, finance, risk, engineering, support, and communications owners.

Recovery
Correct

Use replay-safe requests or authorized ledger adjustments; reconcile before reopening.

After
Learn

Document cause, detection gap, control improvement, and evidence that the fix works.