LoyumiDeveloper docs
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 firstContract version 1.2.0
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.

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.