Webhooks

A webhook is an HTTP call we make to your server. When a payment settles, a wallet transfer is reversed, or a fraud decision is produced, we send the event to your registered endpoint.

Delivery is run by a dedicated service: every delivery is persisted, retried, logged attempt by attempt, and can be replayed.

What a delivery looks like

POST /your-endpoint HTTP/1.1
content-type: application/json
user-agent: Lunixi-Webhook-Service/1.0
x-lunixi-event-id: evt_01J8XQ...
x-lunixi-event-type: payment.captured
x-lunixi-signature: v2=9f2c1a…
x-lunixi-signature-timestamp: 2026-08-17T09:31:44.118Z

Return 2xx and the delivery counts as successful. Any other status triggers a retry.

Verifying the signature

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

{eventId}.{timestamp}.{rawBody}

• eventId — the x-lunixi-event-id header (same as body id)
• timestamp — the exact string value of x-lunixi-signature-timestamp (ISO 8601)
• rawBody — the exact raw request body bytes (UTF-8) — no parsing, no re-serialisation, no canonicalisation

The x-lunixi-signature header carries one or two comma-separated v2=<hex> items. Verification: split the header on ,, compare every v2= item in constant time against the HMAC you computed over the raw body — the signature is valid if any item matches. (The second v2= item is present only during a secret rotation; see below.)

import crypto from 'crypto';
 
export function verifyLunixiWebhook(
  rawBody: string,               // raw body — do NOT parse it
  headers: Record<string, string>,
  signingSecret: string,
  toleranceSeconds = 300,
): boolean {
  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 = crypto
    .createHmac('sha256', signingSecret)
    .update(`${eventId}.${timestamp}.${rawBody}`)
    .digest('hex');
 
  return (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 && crypto.timingSafeEqual(received, wanted);
    });
}

You must check the freshness of x-lunixi-signature-timestamp yourself (recommended tolerance ≤ 300 seconds), so a captured request cannot be replayed later. The example above does this too.

Secret rotation

After you rotate your secret, deliveries are dual-signed with both the new and the old secret for 24 hours (the "grace window"): the header carries two v2= items — the new secret's first, the old one's second (v2=<hexNew>,v2=<hexOld>). A verifier that accepts the signature when any v2= item matches survives rotation with zero downtime — the example above works exactly this way. After 24 hours the old secret stops being used.

Retry policy

A failed delivery is retried on a fixed schedule, with ±20% jitter applied to every wait value:

• 12 attempts total (a ~52-hour horizon); after that the delivery becomes DEAD_LETTER.
• Replaying a DEAD_LETTER delivery resets the attempt budget — it re-enters the queue with a fresh 12 attempts.
• Request timeout defaults to 10 seconds (clamped to 1–30s).
• These limits are configurable per installation; in an on-prem deployment, ask your operator.

Delivery statuses

A DEAD_LETTER delivery is not lost; it can be replayed from the panel or the API. → Webhook Setup

Your endpoint can be disabled automatically

If an endpoint keeps failing consecutively (default threshold 20), its status is set to FAILED and it stops receiving deliveries.

Security: where we will call

The delivery service re-validates the target at call time, not just at registration time:

• Scheme check — http/https only
• IP-class check after resolution — loopback (127.0.0.0/8, ::1), private ranges (10/8, 172.16/12, 192.168/16) and link-local addresses are rejected
• The socket is pinned to the vetted IP — closing the DNS-rebinding window between registration and connect

So your endpoint has to be reachable from the public internet. For local development, use a tunnel (ngrok or similar).

Which products emit events

The webhook backbone is fed from nine sources: organization · payment · subscription · invoice · usage · kyc · fraud · wallet · sanction.

Subscription is per event type — you can subscribe one endpoint to payment.captured and another to wallet.transfer.reversed. For per-product event lists, see that product's pages.

Bank account (bank_account.*) and bank transfer (bank_transfer.*) events are delivered to endpoints of the BANK_CONNECT product. → Bank Accounts › Webhook Events

Insurance events (insurance.*) are delivered to endpoints of the INSURANCE_SERVICE product. → Insurance › Webhook Events

Next

Creating endpoints, subscribing to events, rotating secrets and replaying deliveries: Webhook Setup