Webhooks overview

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

Event types

Event	When	Notes
`CLAIM_CREATED`	User adds a wallet-flow voucher.	Fires from `POST /me/claims`.
`REDEMPTION_CREATED`	User redeems a voucher at an outlet (SUCCESS or FLAGGED).	The bread-and-butter event most partners care about.
`VOUCHER_PUBLISHED`	A 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:

Event	Why not
`FAVORITE_CREATED`	Not 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_UNPUBLISHED`	Voucher-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

Header	Value
`content-type`	`application/json`
`x-event-id`	Same as `body.id`. Useful for log correlation before parsing the body.
`x-event-type`	Same as `body.type`. Lets you route without parsing.
`x-signature`	`t=<unix>,v1=<hex>` — HMAC over the raw body, same algorithm as inbound. See HMAC authentication.

Get started

Concepts

Authentication

Integration surfaces

Webhooks

Reference

Event types

Events not delivered to partner webhooks

Envelope

Headers

Where to go next

Event payloads

Delivery semantics

​Event types

​Events not delivered to partner webhooks

​Envelope

​Headers

​Where to go next

Event payloads

Delivery semantics

Event types

Events not delivered to partner webhooks

Envelope

Headers

Where to go next