Reviewed on 2026-09-19
Verified webhooks
Your endpoint receives events; verify signatures and tolerate retries.
Run examples on your server with your own sandbox data. Never include keys in the frontend. This documentation does not enable live operations.
Secure receipt
Configure a public HTTPS endpoint through the authorized dashboard. Preserve the raw body. LunaPay-Event-Id identifies the event; LunaPay-Signature contains t and v1. HMAC-SHA256 signs eventId.timestamp.rawBody; reject differences over 300 seconds.
Verify before processing
The example rejects missing headers, invalid signatures and nonnumeric or expired timestamps. Then deduplicate the ID and apply changes in a durable transaction; respond 2xx after persistence.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(rawBody, headers, secret, now = Date.now()) {
const id = headers.get('lunapay-event-id');
const signature = headers.get('lunapay-signature');
if (!id || !signature || !secret) return false;
const match = /^t=(\d{1,12}),v1=([a-f0-9]{64})$/.exec(signature);
if (!match) return false;
const timestamp = Number(match[1]);
if (!Number.isSafeInteger(timestamp) ||
Math.abs(now / 1000 - timestamp) > 300) return false;
const expected = createHmac('sha256', secret)
.update(id + '.' + match[1] + '.' + rawBody).digest();
return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}Retries and reconciliation
Deliveries may repeat. Replays retain the event ID. Exactly-once delivery is not promised. Invoice, payment and payout events describe different objects; process them separately. Internal endpoint configuration is not a public /v1 resource.
Development contract · source: Payments · 9f82d06
Next guideResource reference