Receba eventos assinados

Configuração

Webhooks são um recurso Pro configurado em Backend/Webhooks. Cada destino escolhe de 1 a 32 eventos e o gateway aceita até 20 destinos ativos. A URL passa por validação contra SSRF.

Eventos disponíveis

O catálogo atual cobre transação, cliente, link e repasse.

• transaction.created, transaction.succeeded, transaction.failed e transaction.refunded
• customer.created e customer.updated
• checkout_link.created e checkout_link.viewed
• payout.created, payout.paid e payout.failed

Envelope do evento

O mesmo event.id pode reaparecer durante uma retentativa. Trate-o como chave idempotente.

{
  "id": "evt_UUID",
  "type": "transaction.succeeded",
  "data": {},
  "createdAt": "2026-08-04T19:20:00.000Z"
}

Headers de entrega

X-Webhook-Signature contém o HMAC SHA-256 hexadecimal do corpo JSON bruto. X-Webhook-ID identifica o evento e X-Webhook-Timestamp replica createdAt.

Validar a assinatura

Use o segredo exibido apenas na criação. Calcule o HMAC antes de converter o JSON e compare em tempo constante.

const expected = crypto.createHmac("sha256", secret)
  .update(rawBody)
  .digest("hex")

const signature = request.headers.get("x-webhook-signature") ?? ""
const valid = /^[a-f0-9]{64}$/i.test(signature) &&
  crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"))

Entrega e retentativas

Eventos são persistidos em jobs por tenant sem copiar o segredo para a fila. Responda 2xx rapidamente, persista event.id e processe tarefas demoradas de forma assíncrona. Falhas usam lease e backoff.