Saltar para o conteúdo principal

​
Eventos de Webhook

Webhooks permitem que seu sistema receba atualizações em tempo real da Bullring Finance sempre que eventos específicos ocorrerem. Você pode registrar uma URL de webhook para escutar notificações de eventos e acionar seus próprios fluxos de trabalho. A Bullring Finance pode notificar seu servidor em tempo real sobre alterações no status de subcontas, confirmações de pagamento e progresso de saques. Para começar a receber webhooks, registre seu endpoint pelo Painel ou via API de Webhook.

​
Como Funciona

Quando um evento ocorre, a Bullring Finance envia uma requisição HTTP POST para a URL registrada com um payload JSON descrevendo o evento. Seu endpoint deve retornar um código de status 2xx para confirmar o recebimento. Todas as requisições de webhook são assinadas com um segredo compartilhado. Você deve verificar a assinatura da requisição antes de processar.

​
Verificando a assinatura

Todas as requisições de webhook do Bullring incluirão um cabeçalho com a chave X-BULLRING-SIGNATURE, que contém o timestamp e um hash assinado no formato: 
X-BULLRING-SIGNATURE: t={timestamp},v1={hash_string}
Um exemplo de cabeçalho seria: 
{
  ...
  X-BULLRING-SIGNATURE: "t=1492774577,v1=ansdoj213e98jqd928u3eudh239eu2j9d2jd8ejd238eu23ei2d9j23e8u23eue3,",
  ...
}
Para verificar a assinatura:
  • Obtenha o valor do cabeçalho X-BULLRING-SIGNATURE.
  • Divida a string por ,.
  • Em seguida, divida cada parte por =.
  • Extraia o valor no índice 1 de cada parte.
No exemplo acima, você obteria: 
timestamp     // 1492774577
hashString    // ansdoj213e98jqd928u3eudh239eu2j9d2jd8ejd238eu23ei2d9j23e8u23eue3
Para verificar a assinatura, crie um hash usando:
  • O timestamp extraído
  • O payload da requisição (corpo)
  • O segredo (disponível no seu painel do Bullring após criar um webhook)
Depois compare o hash gerado com o hash recebido usando igualdade ==. Como o Bullring utiliza o algoritmo de hash SHA256 com codificação base64, veja abaixo como verificar a assinatura usando Node.js:
Verification Example

import { createHmac } from "crypto";

const receivedHash = hashString;
const payload = JSON.stringify({ ... }); // The request body
const key = "your_secret_key"; // From dashboard

const hash = createHmac("sha256", key)
  .update(`${timestamp},${payload}`)
  .digest("base64");

const isVerified = receivedHash === hash;
Atenção ao uso da vírgula , entre o timestamp e o payload ${timestamp},${payload} ao criar o hash.

​
Eventos de Subconta

  • subaccount.status.created
  • subaccount.status.approved
  • subaccount.status.declined
  • subaccount.status.review
Esses eventos são acionados quando uma nova loja (subconta) é criada ou passa por etapas de verificação KYB.

​
Eventos de Pagamento

  • payment.status.paid
  • payment.status.unpaid
Esses eventos notificam quando uma fatura é paga ou expira sem pagamento.

​
Eventos de Saque

  • withdrawal.status.not_initiated
  • withdrawal.status.in_progress
  • withdrawal.status.completed
  • withdrawal.status.failed
Esses eventos permitem que você acompanhe o status dos saques em reais da sua loja.

​
Formato do Payload do Webhook

Cada webhook será enviado como uma requisição POST para seu endpoint registrado com a seguinte estrutura: 
{
  "event": "event.name",
  "data": {
    "...": "conteúdo específico do evento"
  }
}

​
Exemplos de Payloads

​
Evento de Subconta: subaccount.status.created

{
  "event": "subaccount.status.created",
  "data": {
    "id": "47a79c3d-9a2b-4998-898b-8eb7fad01526",
    "email": "[email protected]",
    "status": "created"
  }
}

​
Evento de Subconta: subaccount.status.approved

{
  "event": "subaccount.status.approved",
  "data": {
    "id": "47a79c3d-9a2b-4998-898b-8eb7fad01526",
    "status": "approved"
  }
}

​
Evento de Pagamento: payment.status.paid

{
  "event": "payment.status.paid",
  "data": {
    "id": "06506c54-8df0-4d5f-bdc0-50dbe29fb84e",
    "amount": 1000,
    "currency": "brl",
    "status": "paid"
  }
}

​
Evento de Pagamento: payment.status.unpaid

{
  "event": "payment.status.unpaid",
  "data": {
    "id": "06506c54-8df0-4d5f-bdc0-50dbe29fb84e",
    "amount": 1000,
    "currency": "brl",
    "status": "unpaid"
  }
}

​
Evento de Saque: withdrawal.status.completed

{
  "event": "withdrawal.status.completed",
  "data": {
    "id": "449eca18-9c77-472c-9e82-b08a18637759",
    "status": "completed",
    "amount": "496.50",
    "currency": "BRL"
  }
}
Certifique-se de que seu servidor esteja preparado para responder com um código de status 2xx para confirmar o recebimento.