ReloadBankDocs
Criar conta

Webhooks

Webhooks

Sempre que uma transação muda para um status relevante, a Reload Bank envia um POST com o objeto da transação para a sua URL. É a forma recomendada de confirmar pagamentos e saques — evite polling.

Configuração

  • Cadastre a URL padrão da sua conta no dashboard, em Webhooks. Lá também ficam o seu secret de assinatura (começa com whsec_) e o botão para enviar um evento de teste (webhook.test).
  • Para direcionar uma transação específica para outra URL, envie postback_url na criação — ela substitui a URL da conta para todos os eventos transaction.* daquela transação.
  • A URL deve usar HTTPS e apontar para um endereço público (IPs privados/internos são bloqueados). Redirecionamentos não são seguidos.

Eventos

Eventos de transação seguem o padrão transaction. + o novo status em minúsculas.

EventoTipoQuando
transaction.paidPIX_INCobrança PIX paga; o líquido já está no saldo disponível.
transaction.expiredPIX_INCobrança PIX venceu sem pagamento.
transaction.completedPIX_OUTSaque liquidado no destino.
transaction.failedPIX_OUTSaque não concluído; valor + taxa voltaram ao saldo.
transaction.canceledPIX_OUTSaque recusado na análise manual; valor + taxa voltaram ao saldo.
webhook.test—Disparado manualmente pelo dashboard para testar a integração.
A criação de uma cobrança PIX (PENDING) ou de um saque (AWAITING_APPROVAL/PROCESSING) e a aprovação de um saque em análise não geram webhook — você é notificado quando o resultado final acontece.

Payload

CampoDescrição
eventNome do evento.
dataO objeto Transação completo, no mesmo formato da API.
created_atMomento em que o evento foi gerado (igual em todas as retentativas).

Headers

HeaderDescrição
X-ReloadBank-EventNome do evento (igual ao campo event).
X-ReloadBank-DeliveryID único da entrega. Mantém-se igual nas retentativas — use para deduplicar.
X-ReloadBank-SignatureAssinatura HMAC no formato t=<unix>,v1=<hex>. Veja Verificar assinatura.

Respondendo

  • Responda com qualquer status 2xx em até 10 segundos. Outros status, timeouts e erros de rede são considerados falha e geram retentativas.
  • Faça o processamento pesado de forma assíncrona (fila) e responda rápido.
  • Seja idempotente: o mesmo evento pode chegar mais de uma vez, e a ordem de chegada não é garantida. Em caso de dúvida, consulte o estado atual com GET /transactions/{id}.
Payload
{
  "event": "transaction.paid",
  "data": {
    "id": "cm2r8x1qz0004lk08abcd1234",
    "external_id": "pedido-1042",
    "type": "PIX_IN",
    "status": "PAID",
    "amount": 100,
    "fee": 1.75,
    "net_amount": 98.25,
    "description": "Pedido #1042",
    "pix": {
      "txid": "K7Q2M9X4T1B8N6R3W5Z0C2V7H",
      "end_to_end_id": "E00000000202610161432K8D2LQ7ZP1M",
      "qr_code": "00020101021226580014br.gov.bcb.pix013600000000-0000-0000-0000-0000000000005204000053039865406100.005802BR5912LOJA EXEMPLO6009SAO PAULO62290525K7Q2M9X4T1B8N6R3W5Z0C2V7H63040000",
      "expires_at": "2026-10-16T15:30:00.000Z"
    },
    "checkout_url": "https://reloadbank.app/pay/cm2r8x1qz0004lk08abcd1234",
    "payer": {
      "name": "Maria Silva",
      "document": "12345678909",
      "email": "[email protected]"
    },
    "failure_reason": null,
    "metadata": {
      "order_id": 1042,
      "channel": "site"
    },
    "paid_at": "2026-10-16T14:32:11.000Z",
    "refunded_at": null,
    "created_at": "2026-10-16T14:30:00.000Z",
    "updated_at": "2026-10-16T14:32:11.000Z"
  },
  "created_at": "2026-10-16T14:32:11.204Z"
}
Headers
POST /webhooks/reloadbank HTTP/1.1
Content-Type: application/json
User-Agent: ReloadBank-Webhooks/1.0
X-ReloadBank-Event: transaction.paid
X-ReloadBank-Delivery: cm2r8y3fk0007lk08mnop3456
X-ReloadBank-Signature: t=1792161131,v1=5f2b7c1e9a0d4c3b8e6f1a2d7c9b0e4f3a6d8c1b2e5f7a9d0c3b6e8f1a4d7c2b