API
Webhooks
Receba payment.confirmed assinado com HMAC-SHA256 no seu backend, com validação e idempotência.
Webhooks notificam seu backend sobre eventos. Reconcile o estado consultando a API, pois a entrega pode falhar.
Configuração
Informe webhookUrl (https) na criação da ordem. A resposta da criação
devolve o objeto webhook com o secret:
{
"webhook": {
"url": "https://meulojista.com/webhooks/caedral",
"secret": "whsec_9f2c…",
"note": "Recebe payment.confirmed assinado (HMAC-SHA256). Guarde o secret."
}
}
O secret é exibido uma única vez na resposta da criação. Guarde-o no
seu cofre de segredos — não é possível recuperá-lo depois.
Evento payment.confirmed
Enviado como POST com corpo JSON quando o pagamento é confirmado on-chain:
{
"event": "payment.confirmed",
"data": {
"ref": "referencia-da-ordem",
"status": "paid",
"token": "USDT",
"chain": "base",
"txHash": "0x..."
},
"timestamp": 1794160000
}
Validação da assinatura
O header X-Caedral-Signature carrega o HMAC-SHA256 do corpo bruto usando
o seu secret. Valide sempre, comparando em tempo constante:
import crypto from 'node:crypto';
export function validarAssinatura(corpoBruto, header, secret) {
const hmac = crypto.createHmac('sha256', secret);
hmac.update(corpoBruto, 'utf8');
const esperado = hmac.digest('hex');
const recebido = String(header ?? '').replace(/^sha256=/, '');
return (
esperado.length === recebido.length &&
crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido))
);
}
Eventos de assinatura usam a URL configurada na assinatura, mas a implementação atual não fornece segredo nem assinatura para eles. Não os trate como prova independente de pagamento. Consulte a ordem para reconciliação.
Regras de consumo
- Responda
2xxrápido — processe de forma assíncrona se necessário; - Seja idempotente — o mesmo evento pode chegar mais de uma vez;
- Não confie no corpo antes de validar a assinatura;
- Persista o
ref— é a chave para consultar a ordem depois.
O backend tenta entregar o evento até três vezes, com timeout de 10 segundos por tentativa. Trate o recebimento de forma idempotente e consulte a ordem para reconciliação.