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."
  }
}
Atenção

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

  1. Responda 2xx rápido — processe de forma assíncrona se necessário;
  2. Seja idempotente — o mesmo evento pode chegar mais de uma vez;
  3. Não confie no corpo antes de validar a assinatura;
  4. 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.