Webhooks

Asynchronous wallet outcomes are delivered by webhook. Learn the result of money movements from webhooks, not polling; the GET endpoints are for confirmation.

Event catalogue

Top-up

Transfers

Withdrawals

Payments and refunds

Loyalty

Invoices and bill pay

Operations

Envelope

Every delivery uses the same envelope; the wallet event's own fields are under data:

{
  "id": "0b6d3f2e-9a41-4c7e-8d25-6f1a3b9c4e07",
  "type": "wallet.transfer.completed",
  "sourceService": "wallet-service",
  "organizationId": "3c9a1e5b-7d2f-4b8e-a6c4-1f0e9d2b7a35",
  "productCode": "WALLET_SERVICE",
  "environment": "LIVE",
  "eventVersion": 1,
  "schemaVersion": "v1",
  "createdAt": "2026-08-07T12:00:04.512Z",
  "data": {
    "schemaVersion": "wallet.webhook.v1",
    "domain": "WALLET",
    "eventName": "wallet.transfer.completed",
    "operationId": "7a3e9c1d-2b4f-4e8a-9d6c-0f5b8e2a1c93",
    "sourceWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
    "destinationWalletAccountId": "a4d7b0e3-5f8c-4a1d-9b2e-6c3f8a1d0e59",
    "amount": "10050",
    "currency": "TRY",
    "feeTotal": "250",
    "taxTotal": "125"
  }
}

Inside data:

Event-specific fields (operation id, amounts, status) accompany them inside data.

Signature verification

Every delivery carries these headers:

The v2 signature is an HMAC of the raw body — you verify it without parsing the body:

signature = HMAC-SHA256( secret, "{eventId}.{timestamp}.{rawBody}" )

Compare every v2= item in the header against this value in constant time; the signature is valid if any matches (during the 24-hour grace window of a secret rotation there are two v2= items).

import { createHmac, timingSafeEqual } from 'node:crypto';
 
export function verifyWalletWebhook(rawBody, headers, secret, toleranceSeconds = 300) {
  const eventId   = headers['x-lunixi-event-id'];
  const timestamp = headers['x-lunixi-signature-timestamp'];
  if (Math.abs(Date.now() - Date.parse(timestamp)) > toleranceSeconds * 1000) return false;
 
  const expected = createHmac('sha256', secret)
    .update(`${eventId}.${timestamp}.${rawBody}`)
    .digest('hex');
 
  return String(headers['x-lunixi-signature'] || '')
    .split(',')
    .map((item) => item.trim())
    .filter((item) => item.startsWith('v2='))
    .some((item) => {
      const received = Buffer.from(item.slice(3), 'hex');
      const wanted = Buffer.from(expected, 'hex');
      return received.length === wanted.length && timingSafeEqual(received, wanted);
    });
}

Delivery guarantee

Wallet webhooks are delivered at least once:

• When an operation changes state (e.g. completed, failed, reversed), the corresponding event is recorded in the same transaction as the state change. If an operation reached a state, the event for that state exists; an infrastructure outage does not lose it — it is delivered late once the outage is over.
• The same event can be delivered more than once. Every repeat carries the same x-lunixi-event-id; the value is fixed per event and should be used as your deduplication key.
• Events can arrive late. You can always confirm the current state of an operation with GET /wallet/operations/{id}.

Retries

If your endpoint does not return 2xx, delivery is retried. Waits follow a fixed schedule with ±20% jitter applied to every value; once attempts are exhausted the delivery is marked dead letter.

Consuming correctly

1. Return 2xx fast. Queue the work; do not do long processing inside the webhook request — a timeout causes retries.
2. Be idempotent. Delivery is at least once; the same event can arrive more than once. Store x-lunixi-event-id and ignore repeats carrying the same id.
3. There is no ordering guarantee. completed can arrive before processing. Write state from the event's content, not its arrival order; confirm with GET /wallet/operations/{id} when in doubt.
4. Ignore unknown events. New event types can be added; return 2xx for a type you do not recognize.
5. Do not return 3xx. Redirects are not followed.

Setup

Register your endpoint URL and the events you want in the merchant panel; your signing secret is generated there. The endpoint must be publicly reachable over HTTPS.

Common mistakes