Webhooks Overview

Loyalite outbound webhooks notify your server when loyalty events happen in real time.

Payload structure

Every webhook request is an HTTP POST with a JSON body in this shape:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event": "stamp.earned",
  "occurred_at": "2026-04-19T14:30:00Z",
  "organization": "kahveci-mehmet",
  "data": {
    "customer_code": 482193,
    "customer_id": "a1b2c3d4-...",
    "stamps_added": 1,
    "stamp_balance": 5,
    "max_stamps": 10,
    "source": "webhook",
    "transaction_id": "7c9e6679-..."
  }
}

Field	Type	Description
`id`	UUID	Unique delivery ID — use for idempotency
`event`	string	Event type (see Event Reference)
`occurred_at`	ISO 8601	Timestamp when the event occurred (UTC)
`organization`	string	Your store's subdomain slug
`data`	object	Event-specific payload (varies by event type)

Request headers

Loyalite sends these headers with every webhook request:

Header	Value
`Content-Type`	`application/json`
`X-Loyalite-Signature-256`	`sha256=<hex>` — HMAC-SHA256 of the request body
`X-Loyalite-Event`	Event type, e.g. `stamp.earned`
`X-Loyalite-Delivery`	Delivery UUID — same as `id` in the payload

Your server requirements

Your endpoint must be reachable over HTTPS (HTTP is rejected at registration)
Respond with a 2xx status code within 10 seconds — anything else is treated as a failure and retried
Process events asynchronously if needed — return 200 immediately and handle in a background job
Use the id field for idempotency (opens in a new tab) — the same delivery may arrive more than once on retry

Event types

Event	Trigger
`stamp.earned`	Customer earns stamps
`stamp.redeemed`	Stamp card fills during an earn — reward coupon issued
`points.earned`	Customer earns points
`points.spent`	Customer spends points
`coupon.redeemed`	Customer redeems a coupon
`customer.enrolled`	New customer registers

See Event Reference for full payload schemas.

Introduction Setup