Revisado em 19/09/2026
Webhooks verificados
Seu endpoint recebe eventos; verifique assinaturas e tolere reenvios.
Execute os exemplos no seu servidor com seus próprios dados de sandbox. Nunca inclua chaves no frontend. Esta documentação não habilita operações live.
Recepção segura
Configure endpoint HTTPS público pelo painel autorizado. Preserve o corpo bruto. LunaPay-Event-Id identifica o evento; LunaPay-Signature contém t e v1. HMAC-SHA256 assina eventId.timestamp.rawBody; rejeite diferenças superiores a 300 segundos.
Verifique antes de processar
O exemplo rejeita cabeçalhos ausentes, assinaturas inválidas e timestamps não numéricos ou vencidos. Depois, deduplique o ID e aplique alterações em transação durável; responda 2xx após 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'));
}Reenvios e conciliação
Entregas podem se repetir. Replays mantêm o ID. Não se promete entrega exatamente uma vez. Eventos de fatura, pagamento e retirada descrevem objetos distintos; processe separadamente. A configuração interna de endpoints não é recurso público /v1.
Contrato de desenvolvimento · fonte: Payments · 9f82d06
Próximo guiaReferência de recursos