Webhooks & IPN

Two push channels tell your backend what happened, so you don’t have to poll:

Webhooks — one per-merchant URL that receives EVERY payment event.
IPN — an optional per-payment callback (ipnCallbackUrl at creation).

Both are signed.

Always verify the signature, and never credit an order from a push alone. Treat the push as a hint and confirm the state with GET /api/v1/payments/:id before releasing goods.

Webhook configuration

Config lives at /api/v1/me/webhook and requires a dashboard JWT. Roles: merchant_admin / merchant_member (+ webhooks:view / webhooks:manage).

Endpoint	What it does
`GET /`	`{"webhookUrl":"","hasSecret":true}` — never returns the secret.
`PATCH /`	Set the URL: `{"webhookUrl":"https://..."}`. HTTPS enforced (`400 INVALID_WEBHOOK_URL "Webhook URL must use HTTPS"`) and internal addresses rejected (SSRF guard: `"Webhook URL must not point to internal addresses"`). Empty string clears it. Rate 10/min.
`POST /rotate-secret`	Returns `{webhookUrl, webhookSecret}` — the 64-hex secret is shown only here; store it. The old secret stops verifying immediately. Rate 3/min.
`GET /deliveries?page=&limit=`	Delivery log: `{"items":[],"pagination":{"total":0,"page":1,"limit":10,"hasMore":false}}`. Each row records event, status, response code, attempts.
`GET /deliveries/:id`	Full delivery detail, including the exact payload + signature sent.
`POST /deliveries/:id/replay`	Re-send a delivery (new delivery id). Rate 20/min.

POST /rotate-secret is the only time the 64-hex signing secret is ever visible — store it in your secrets manager the moment it is returned. The old secret stops verifying immediately.

Webhook delivery format

Each event is POSTed to your URL with these headers:

Header	Content
`x-liddie-sig`	`HMAC-SHA256(secret, "<timestamp>.<rawBody>")`, hex.
`x-liddie-timestamp`	Unix seconds when signed.
`x-liddie-event`	Event name (see the catalog below).
`x-liddie-delivery-id`	Idempotency key — dedupe on this: retries and replays of the same logical event reuse it.

Verification recipe — do all four:

Reject stale timestamps

Reject the delivery if |now − x-liddie-timestamp| > 300 seconds (the replay window).

Verify the signature

Compute HMAC-SHA256(yourSecret, timestamp + "." + rawBody) over the raw body bytes (do not re-serialize JSON) and compare constant-time with x-liddie-sig.

Verify signature

// Node example
const crypto = require('node:crypto');
const ok = (req, rawBody, secret) => {
  const ts = Number(req.headers['x-liddie-timestamp']);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const got = String(req.headers['x-liddie-sig'] ?? '');
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
};

Dedupe on the delivery id

Dedupe on x-liddie-delivery-id — retries and replays of the same logical event reuse it.

Acknowledge fast, work async

Respond 2xx fast (under 10 s); do slow work async. Non-2xx triggers automatic retries with backoff.

A verified push is still a hint, not proof: confirm the payment state with GET /api/v1/payments/:id before releasing goods.

Event catalog

Event	Fired when
`payment.confirming`	Deposit seen, awaiting confirmations.
`payment.partially_paid`	Deposit below the payable amount. Fired once per top-up (each new paid total is a new logical event): an invoice paid in two installments gets a `partially_paid` for the first deposit and then the normal `confirming` → `finished` sequence once fully funded — receiving both is expected, not a duplicate. Dust-sized top-ups are suppressed (anti-griefing) and accumulate into the next notification.
`payment.confirmed`	Reserved — NOT emitted in the current release. A confirmed deposit transitions straight into settlement, so use `payment.finished` as the credit signal.
`payment.finished`	The deposit was swept and the net amount was credited to your Liddie balance — the “you got paid” event.
`payment.expired` / `payment.cancelled`	Terminal non-success.
`payment.failed`	Reserved — NOT emitted in the current release. No code path transitions a payment to FAILED; terminal non-success surfaces as expired or cancelled.
`payment.cross_chain_processed`	A wrong-currency/overpaid deposit was accepted (manually or by auto-accept).
`payment.repeat_deposit_processed`	A second deposit to an already-settled address became a child payment (`parentPaymentId` in the payload).

Every event other than payment.partially_paid fires at most once per payment (deduped per payment + event); dedupe on x-liddie-delivery-id regardless. Payloads carry the payment’s public fields plus your metadata echoed verbatim.

IPN (per-payment callback)

If you set ipnCallbackUrl when creating a payment, terminal and major transitions of THAT payment are also POSTed there. The same SSRF/HTTPS rules as webhooks apply. The IPN signature (v2) differs from the webhook channel:

Headers: x-liddie-sig, x-liddie-timestamp, and x-liddie-delivery-id.
Timestamp units differ from webhooks. IPN signs and sends x-liddie-timestamp in Unix milliseconds (Date.now()), whereas the webhook channel uses Unix seconds. Reusing the webhook staleness check (|now_seconds − ts| > 300) on IPN compares seconds against milliseconds and rejects every delivery. For IPN, stay in milliseconds: reject when |Date.now() − Number(x-liddie-timestamp)| > 300000 (a 300-second window).
Scheme: HMAC-SHA512 with a per-merchant derived key over the timestamped, canonically key-sorted JSON body: sig = HMAC-SHA512( HMAC-SHA512(IPN_HMAC_SECRET, merchantId), "<ts>.<body>" ), where <ts> is that millisecond value.
The platform operator gives you your per-merchant IPN key (HMAC-SHA512(IPN_HMAC_SECRET, merchantId)) — you verify with that key; you never hold the platform-wide secret.
IPN is at-least-once. The same transition can be delivered more than once, so dedupe on x-liddie-delivery-id. It is stable per paymentId:status (with the paid amount appended for partial top-ups), which lets a consumer collapse duplicate deliveries of the same logical event.

Webhooks (one URL, all events, self-service secret) are the recommended channel; use IPN when a specific order needs its own callback target.

What you cannot do

Read the current webhook secret (rotate to get a new one).
Configure webhooks/IPN keys with an API key (dashboard only).
Receive events for another merchant (deliveries are tenant-scoped end to end).

Get webhook config

Read your current webhook URL and whether a secret is set.

Rotate webhook secret

Mint the 64-hex signing secret used by the verification recipe.

Get a payment

The source of truth to re-check state after any push.

API Overview

Credentials, response envelopes, and rate limits.

Get started

Guides

Webhooks & IPN

Webhook configuration

Webhook delivery format

Event catalog

IPN (per-payment callback)

What you cannot do

Get webhook config

Rotate webhook secret

Get a payment

API Overview

​Webhook configuration

​Webhook delivery format

​Event catalog

​IPN (per-payment callback)

​What you cannot do

Get webhook config

Rotate webhook secret

Get a payment

API Overview

Webhook configuration

Webhook delivery format

Event catalog

IPN (per-payment callback)

What you cannot do