Configure and verify webhooks

Each merchant can configure one webhook per environment. LirPay stores test and live secrets and event journals separately.

GEThttps://lirpay.org/api/v2/integration/webhook

Read the current environment webhook without exposing its secret.

API key requiredwebhooks:read

PUThttps://lirpay.org/api/v2/integration/webhook

Create or update the webhook URL, subscriptions, and enabled state.

API key requiredwebhooks:write

Parameter	Type	In	Required	Description
url	URL	body	yes	HTTPS endpoint in live mode. Test mode also accepts HTTP.
event_types	string[]	body	yes	Non-empty list of supported events.
enabled	boolean	body	no	Delivery state. Defaults to true.

Request

{
  "url": "https://merchant.example/webhooks/lirpay",
  "event_types": [
    "payment.succeeded",
    "balance.updated",
    "withdrawal.completed"
  ],
  "enabled": true
}

The first PUT response includes a new secret. Store it because later GET responses expose only has_secret.

DELETEhttps://lirpay.org/api/v2/integration/webhook

Disable webhook delivery for the current environment.

API key requiredwebhooks:write

POSThttps://lirpay.org/api/v2/integration/webhook/test

Send and record a signed test event.

API key requiredwebhooks:write

POSThttps://lirpay.org/api/v2/integration/webhook/rotate-secret

Replace the signing secret and return the new value once.

API key requiredwebhooks:write

GEThttps://lirpay.org/api/v2/integration/webhook-events

List event payloads and delivery state.

API key requiredwebhooks:read

Parameter	Type	In	Required	Description
page	integer	query	no	Page number. Defaults to 1.
limit	integer	query	no	Items per page. Maximum 100.

GEThttps://lirpay.org/api/v2/integration/webhook-events/{id}

Read one payload and its delivery history.

API key requiredwebhooks:read

Parameter	Type	In	Required	Description
id	uuid	path	yes	Resource identifier returned by a list or create operation.

The delivery_history array includes attempt number, status, error, and timestamp.

POSThttps://lirpay.org/api/v2/integration/webhook-events/{id}/redeliver

Deliver an existing event again.

API key requiredwebhooks:writeIdempotency-Key required

Parameter	Type	In	Required	Description
id	uuid	path	yes	Resource identifier returned by a list or create operation.
Idempotency-Key	string	header	yes	Unique key for this monetary operation. Maximum 255 characters.

Allowlist source IPs

Production webhook deliveries come from payment-core egress. Allowlist 2.27.27.132 for both test and live events.

2.27.27.132 — webhook source IP
Do not allowlist 2.27.27.134. That address is HTTPS ingress for lirpay.org only.
Deliveries currently use IPv4 only. Verify the HMAC signature even if you filter by IP.

Verify each signature

Compute a hexadecimal Hash-based Message Authentication Code using SHA-256 (HMAC-SHA256) over the untouched request body.

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", webhookSecret)
  .update(rawBody)
  .digest("hex");
const valid = timingSafeEqual(
  Buffer.from(expected, "hex"),
  Buffer.from(signature, "hex"),
);

Read the event identifier from X-Lirpay-Event-Id
Read the environment from X-Lirpay-Mode
Return a 2xx response after persisting the event
Deduplicate processing by event identifier
Live deliveries are retried up to eight times. Test-mode events are never retried

Subscribe to supported events

payment.succeeded, payment.failed, payment.expired, payment.refund_required, payment.refunded, payment.chargeback
balance.updated
withdrawal.processing, withdrawal.completed, withdrawal.failed
conversion.completed