Skip to main content
We POST JSON to your webhookUrl whenever a user-relevant event happens.

​
Event types

EventWhenNotes
CLAIM_CREATEDUser adds a wallet-flow voucher.Fires from POST /me/claims.
REDEMPTION_CREATEDUser redeems a voucher at an outlet (SUCCESS or FLAGGED).The bread-and-butter event most partners care about.
VOUCHER_PUBLISHEDA merchant the user has favorited publishes a new voucher.Fanned out at publish time — one event per favoriting user.

​
Events not delivered to partner webhooks

A few internal events flow through the same notification table but never reach your webhookUrl:
EventWhy not
FAVORITE_CREATEDNot part of the partner contract. If you need to know when your users favorite merchants, call GET /me/favorites from the webview.
VOUCHER_EXPIRED / VOUCHER_UNPUBLISHEDVoucher-level signals (no recipient_user_id). Partners that need them can subscribe to a dedicated polling endpoint — talk to us if you have a use case. Today they exist only so the internal admin / main-app can clean caches.

​
Envelope

Every webhook shares the same outer shape: 
{
  "id": "9f1a2c4d-5e6f-7891-a2b3-c4d5e6f78901",   // event UUID. Use for idempotency.
  "type": "REDEMPTION_CREATED",                     // see table above
  "createdAt": "2026-05-12T08:14:22.501Z",          // when the event row was written
  "data": {
    "userId": "8d2a7f3b-...",                       // our internal user ID
    "externalUserId": "usr_demo_001",               // your external ID (always present for partner users)
    // ... event-specific fields ...
  }
}

​
Headers

HeaderValue
content-typeapplication/json
x-event-idSame as body.id. Useful for log correlation before parsing the body.
x-event-typeSame as body.type. Lets you route without parsing.
x-signaturet=<unix>,v1=<hex> — HMAC over the raw body, same algorithm as inbound. See HMAC authentication.

​
Where to go next

Event payloads

The full payload shape for each event type, with a verification snippet.

Delivery semantics

Retry schedule, idempotency, receiver checklist.