Bravive

Admin API Docs

HOME

Introdução

HOOKS

Webhooks

Os webhooks permitem que você receba notificações em tempo real sobre eventos importantes em sua conta. Configure URLs de webhook no painel administrativo para receber atualizações automáticas.

Configuração

Para configurar um webhook, você precisa:

Acessar o painel administrativo
Navegar até Configurações > Webhooks
Adicionar uma nova URL de webhook
Selecionar os eventos que deseja receber

Eventos Disponíveis

Você pode configurar webhooks para os seguintes eventos:

Eventos de Pagamento:

on_transaction_created - Quando um pagamento é criado
on_transaction_updated - Quando um pagamento é atualizado
on_transaction_approved - Quando um pagamento é aprovado
on_transaction_rejected - Quando um pagamento é rejeitado
on_transaction_canceled - Quando um pagamento é cancelado
on_transaction_chargeback - Quando ocorre um chargeback
on_transaction_refunded - Quando um pagamento é reembolsado

Eventos de Saque:

on_withdraw_created - Quando um saque é criado
on_withdraw_updated - Quando um saque é atualizado
on_withdraw_approved - Quando um saque é aprovado
on_withdraw_rejected - Quando um saque é rejeitado

Formato do Payload

O payload do webhook varia de acordo com o tipo de evento:

{
  "id": "string",
  "type": "PAYMENT",
  "status": "APPROVED | REJECTED | CANCELED | CHARGEBACK | REFUNDED | IN_DISPUTE",
  "amount": 1000,
  "currency": "BRL",
  "external_id": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "payer": {
    "name": "João Silva",
    "email": "[email protected]",
    "document": "123.456.789-00"
  },
  "payment_method": {
    "type": "PIX",
    "details": {}
  }
}

{
  "id": "string",
  "type": "WITHDRAW",
  "withdraw_status": "APPROVED | REJECTED | CANCELED",
  "amount": 1000,
  "currency": "BRL",
  "external_id": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "recipient": {
    "name": "Maria Santos",
    "email": "[email protected]",
    "document": "987.654.321-00"
  },
  "bank_account": {
    "bank_code": "001",
    "agency": "1234",
    "account": "12345-6"
  }
}

Segurança

Para garantir a segurança dos webhooks, recomendamos as seguintes práticas:

Sempre use HTTPS em suas URLs de webhook
Valide a origem dos webhooks verificando o cabeçalho de assinatura
Implemente idempotência em seu endpoint para evitar processamento duplicado
Configure timeouts apropriados para evitar bloqueios

Configuração do Endpoint

Seu endpoint deve:

Aceitar requisições POST
Retornar status HTTP 200 para confirmar o recebimento
Processar o webhook em até 10 segundos
Implementar retry logic para falhas temporárias

Os webhooks são enviados via POST para a URL configurada. Certifique-se de que seu endpoint esteja preparado para receber requisições POST e retornar um status 200 para confirmar o recebimento.

Em caso de falha na entrega do webhook, nosso sistema fará automaticamente até 3 tentativas de reenvio, com intervalo de 5 minutos entre cada tentativa.