Refera te avisa quando algo acontece.

Cadastra uma URL no dashboard e escolhe quais eventos quer receber. A gente entrega via POST com corpo JSON + assinatura HMAC-SHA256 no cabeçalho.

Eventos disponíveis

• partner.created — novo parceiro entrou no programa.
• conversion.recorded — conversão registrada.
• commission.available — comissão nasceu (venda ou conversion).
• withdrawal.requested — vendedor pediu PIX.
• withdrawal.status_changed — saque foi aprovado/pago/rejeitado.

Headers enviados

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-Refera-Event: commission.available
X-Refera-Signature: sha256=8f2a...
User-Agent: Refera-Webhook/1.0

Verificando a assinatura

Cada endpoint tem um secret que você recebeu ao criar o webhook. Assine o corpo RAW e compare em constant-time:

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyReferaSignature(rawBody: string, header: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(header)
  return a.length === b.length && timingSafeEqual(a, b)
}

Retry policy

Hoje é fire-and-forget — a Refera tenta uma vez, timeout de 5s. Se seu endpoint estiver fora, o evento se perde. Recomendamos idempotência no seu lado (guardar {event_id} se você quer garantia). Vamos adicionar retry com backoff em breve.

Payload exemplo

{
  "event": "commission.available",
  "event_id": "evt_01HXY...",
  "created_at": "2026-08-06T14:38:20Z",
  "tenant_id": "5e7bde52-...",
  "data": {
    "commission_id": "d1b78e05-...",
    "partner_id": "278ddb3b-...",
    "amount_brl": 14.99,
    "source_sale_id": "a8f2c341-..."
  }
}