Revisado el 19/09/2026
Webhooks verificados
Tu endpoint recibe eventos; debe verificar su firma y tolerar reintentos.
Ejemplos para ejecutar en tu servidor con datos propios de sandbox. Las claves nunca se incluyen en el frontend. Esta documentación no habilita operaciones live.
Recepción segura
Configurá un endpoint HTTPS público desde el panel autorizado. Conservá el cuerpo crudo. LunaPay-Event-Id identifica el evento y LunaPay-Signature contiene t y v1. La firma HMAC-SHA256 cubre eventId.timestamp.rawBody; rechazá diferencias de más de 300 segundos.
Verificar antes de procesar
El ejemplo rechaza cabeceras ausentes, firmas inválidas y timestamps no numéricos o vencidos. Después de verificar, deduplicá el ID y aplicá el cambio dentro de una transacción durable; respondé 2xx después de persistir.
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'));
}Reintentos y conciliación
Las entregas pueden repetirse. Los replays conservan el ID del evento. No se promete entrega exactamente una vez. Un evento de factura, pago o retiro informa objetos distintos; procesalos por separado. La configuración interna de endpoints no es un recurso público /v1.
Contrato de desarrollo · fuente: Payments · 9f82d06
Siguiente guíaReferencia de recursos