Reborn
Docs

Webhooks

Receba eventos HTTP em tempo real na sua URL — pagamentos, estornos e status do seller.

Webhooks são configurados por seller via API (autenticação com X-Api-Key). A Reborn envia um POST JSON para a URL cadastrada sempre que um evento ocorre e as condições abaixo são atendidas.

  1. Cadastrar a URL em POST /v1/sellers/{sellerId}/webhooks com os eventTypes desejados.
  2. Guardar o secret retornado na criação — ele não é exibido novamente e serve para validar o header X-Reborn-Signature.
  3. No dashboard do seller, em Configurações → Notificações, manter o canal Webhook habilitado para o tipo de evento (ex.: pagamento confirmado, estorno).
  4. Endpoint público em HTTPS, respondendo 2xx em até alguns segundos.

Criar webhook
curl -X POST "https://sandbox-api.rebornpay.io/v1/sellers/{sellerId}/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: rk_..." \
  -d '{
    "url": "https://seuservidor.com/webhooks/rebornpay",
    "eventTypes": ["TRANSACTION_PAID", "TRANSACTION_REFUNDED"],
    "description": "ERP produção"
  }'

Use ALL em eventTypes para assinar todos os tipos suportados, ou liste explicitamente (recomendado em produção).

eventType (cadastro)Quando dispara
TRANSACTION_PAIDPagamento confirmado (PIX, cartão, etc.)
TRANSACTION_REFUNDEDEstorno concluído na adquirente
TRANSACTION_CANCELLEDTransação cancelada antes do pagamento
SELLER_STATUS_CHANGEDKYC aprovado ou rejeitado
CHARGEBACK_RECEIVEDChargeback ou alerta pre-chargeback
SETTLEMENT_PAIDLiquidação paga ao seller
PAYMENT_LINK_*Criação, atualização ou expiração de link

Cada entrega é um POST com JSON no body. Além de Content-Type, a Reborn envia o header de assinatura abaixo.

HeaderValor
Content-Typeapplication/json
Acceptapplication/json
X-Reborn-SignatureHMAC-SHA256 do body bruto (hex minúsculo), usando o secret do webhook
Exemplo de requisição recebida
POST /webhooks/rebornpay HTTP/1.1
Host: seuservidor.com
Content-Type: application/json
Accept: application/json
X-Reborn-Signature: a1b2c3d4e5f6789...  // HMAC-SHA256 hex (body bruto + secret)

{"type":"TRANSACTION_PAID","sellerId":"...","occurredAt":"...","data":{...}}

Todos os webhooks seguem o envelope abaixo. O campo type repete o tipo do evento;occurredAt está em UTC.

Para TRANSACTION_PAID e TRANSACTION_REFUNDED, data.transaction usa o mesmo schema de GET /v1/transactions/{id} (valores em centavos, documento mascarado).

TRANSACTION_PAID
{
  "type": "TRANSACTION_PAID",
  "sellerId": "ca31b75f-ba3f-491c-9971-aff7d99e4ec5",
  "occurredAt": "2026-06-18T03:04:08.479374",
  "data": {
    "transaction": {
      "id": "f81a8a94-b0d8-44f3-850f-aa699e664b62",
      "status": "PAID",
      "paymentMethod": "PIX",
      "amount": 50,
      "currency": "BRL",
      "description": "Pedido #1234",
      "customer": {
        "name": "João da Silva",
        "email": null,
        "document": "***982247-**"
      },
      "paymentDetails": {
        "qrCode": "00020126580014br.gov.bcb.pix...",
        "qrCodeUrl": null,
        "expiresAt": "2026-06-18T04:00:24.047"
      },
      "createdAt": "2026-06-18T03:00:21.417691",
      "updatedAt": "2026-06-18T03:03:51.161477",
      "paidAt": "2026-06-18T03:03:51.141472",
      "refunds": []
    }
  }
}

Em TRANSACTION_REFUNDED, status é REFUNDED e refunds lista os estornos com COMPLETED quando aplicável.

Demais eventos enviam data.details com metadados específicos do evento. O endpoint POST .../webhooks/{id}/test envia o mesmo formato com test: true no body (apenas para validar conectividade — eventos reais de pagamento não incluem esse campo).

O secret é retornado uma única vez ao criar o webhook. Guarde-o no seu servidor (variável de ambiente ou secrets manager) — nunca no frontend.

Algoritmo
// Algoritmo (igual em todas as entregas)
// secret  = valor retornado em POST /webhooks (whsec_...)
// rawBody = bytes exatos do POST, como string UTF-8, ANTES do JSON.parse
//
// X-Reborn-Signature = HMAC_SHA256(key=secret, message=rawBody).hexdigest()
//
// Node.js:
// crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")

Use o body bruto da requisição (string ou bytes exatos antes do parse). Re-serializar o JSON invalida a assinatura porque a ordem dos campos pode mudar.

Node.js
import crypto from "node:crypto";

/** Use o body bruto (string) exatamente como recebido — antes do JSON.parse. */
export function verifyRebornWebhook(
  rawBody: string,
  secret: string,
  signatureHeader: string | null,
): boolean {
  if (!signatureHeader) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, "utf8"),
      Buffer.from(signatureHeader, "utf8"),
    );
  } catch {
    return false;
  }
}

// Express: app.post('/webhooks/rebornpay', express.raw({ type: 'application/json' }), ...)
Python
import hmac
import hashlib

def verify_reborn_webhook(raw_body: bytes, secret: str, signature_header: str | None) -> bool:
    if not signature_header:
        return False
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

  • Respostas fora da faixa 2xx ou timeout (~15s) são reprocessadas até 5 tentativas, com intervalo padrão de 60s entre elas.
  • Trate cada entrega como idempotente: use type + data.transaction.id (ou identificador em data.details) para ignorar duplicatas.
  • Consulte o histórico em GET /v1/sellers/{sellerId}/webhooks/deliveries (status, HTTP da última tentativa, erros).
Histórico de entregas
curl "https://sandbox-api.rebornpay.io/v1/sellers/{sellerId}/webhooks/deliveries?limit=20" \
  -H "X-Api-Key: rk_..."

Dispare um evento de exemplo para validar URL, TLS e verificação de assinatura antes de ir a produção:

Evento de teste
curl -X POST "https://sandbox-api.rebornpay.io/v1/sellers/{sellerId}/webhooks/{webhookId}/test" \
  -H "X-Api-Key: rk_..."

O teste usa o primeiro eventType cadastrado no webhook e envia uma transação fictícia em data.transaction.

Schemas completos dos endpoints em API Reference → Webhooks. Autenticação da API em Autenticação.