Webhooks e Notificações

​

Visão Geral

​

Como Funcionam

​

Conceito Base

​

Características Principais

• Notificações em tempo real para todos os eventos importantes
• URLs específicas por transação para maior flexibilidade
• Retry automático em caso de falha de entrega
• Assinatura digital para validação de autenticidade

​

Configuração

​

URLs por Produto

​

Configuração via API

curl --request POST \
  --url https://api-gateway.firebanking.com.br/business/webhook \
  --header 'Content-Type: application/json' \
  --header 'apiKey: sua_chave_api' \
  --data '{
    "pixWebhookUrl": "https://meusite.com/webhooks/pix",
    "bankSlipWebhookUrl": "https://meusite.com/webhooks/boleto",
    "creditCardWebhookUrl": "https://meusite.com/webhooks/cartao"
  }'

​

URLs Específicas por Transação

{
  "amount": 10000,
  "callback_url": "https://meusite.com/webhook/transacao-especifica",
  "buyer": {
    "email": "[email protected]"
  }
}

​

Webhook de Onboarding

{
  "onboardingWebhookUrl": "https://meusite.com/webhooks/onboarding"
}

​

Eventos Disponíveis

​

Transações de Cartão

• payment.authorized - Pagamento autorizado com sucesso
• payment.captured - Valor capturado efetivamente
• payment.failed - Falha na autorização do pagamento
• payment.expired - Pré-autorização expirada (7 dias)
• payment.refunded - Estorno processado
• payment.cancelled - Transação cancelada

​

Assinaturas Recorrentes

• subscription.created - Nova assinatura criada
• subscription.payment_successful - Cobrança recorrente bem-sucedida
• subscription.payment_failed - Falha na cobrança recorrente
• subscription.cancelled - Assinatura cancelada
• subscription.suspended - Assinatura suspensa por falha

​

PIX Cash In (Cobrança)

• pix.charge.created - Cobrança PIX criada com sucesso
• pix.charge.paid - Pagamento PIX recebido
• pix.charge.expired - Cobrança PIX expirada
• pix.charge.cancelled - Cobrança PIX cancelada

​

PIX Cash Out (Saque)

• pix.withdraw.created - Saque PIX criado
• pix.withdraw.processed - Saque PIX processado com sucesso
• pix.withdraw.failed - Falha no processamento do saque
• pix.withdraw.cancelled - Saque PIX cancelado

​

Boleto Bancário

• bankslip.created - Boleto gerado com sucesso
• bankslip.paid - Boleto pago pelo cliente
• bankslip.expired - Boleto vencido
• bankslip.cancelled - Boleto cancelado

​

Onboarding

• onboarding.started - Processo de onboarding iniciado
• onboarding.completed - Onboarding finalizado com sucesso
• onboarding.rejected - Onboarding rejeitado
• onboarding.pending_documents - Documentos pendentes

​

Estrutura do Payload

​

Cabeçalhos HTTP

POST /webhook HTTP/1.1
Host: meusite.com
Content-Type: application/json
X-FireBanking-Signature: sha256=abc123...
X-FireBanking-Event: payment.captured
User-Agent: FireBanking-Webhooks/1.0

​

Corpo da Requisição

{
  "event": "payment.captured",
  "transaction_id": "fb_trans_123456789",
  "external_id": "pedido-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "fb_trans_123456789",
    "status": "captured",
    "amount": 10000,
    "currency": "BRL",
    "captured_amount": 10000,
    "buyer": {
      "email": "[email protected]",
      "document": "***.***.***-**"
    },
    "created_at": "2024-01-15T10:25:00Z",
    "captured_at": "2024-01-15T10:30:00Z"
  }
}

​

Validação de Segurança

​

Verificação de Assinatura

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

​

Validação de Origem

• HTTPS obrigatório: Todas as URLs de webhook devem usar protocolo HTTPS
• IPs autorizados: Verifique se a requisição origina dos IPs do FireBanking
• Timestamp: Valide o timestamp para evitar ataques de replay
• URLs HTTP rejeitadas: URLs HTTP serão rejeitadas com erro 400

​

Implementação Robusta

​

Tratamento de Resposta

HTTP/1.1 200 OK
Content-Length: 0

• Status 200-299: Webhook processado com sucesso
• Outros status: FireBanking tentará reenviar

​

Retry Policy

• Tentativas: Até 5 tentativas com backoff exponencial
• Intervalo: 1s, 3s, 9s, 27s, 81s
• Timeout: 30 segundos por tentativa

​

Idempotência

def process_webhook(webhook_data):
    transaction_id = webhook_data['transaction_id']
    
    # Verifica se já foi processado
    if webhook_already_processed(transaction_id):
        return "OK"  # Resposta de sucesso sem reprocessar
    
    # Processa o webhook
    process_transaction_update(webhook_data)
    mark_webhook_as_processed(transaction_id)
    
    return "OK"

​

Gerenciamento de Webhooks via API

​

Consultar Configuração Atual

curl --request GET \
  --url https://api-gateway.firebanking.com.br/business/webhook \
  --header 'apiKey: sua_chave_api'

{
  "pixWebhookUrl": "https://meusite.com/webhooks/pix",
  "bankSlipWebhookUrl": "https://meusite.com/webhooks/boleto",
  "creditCardWebhookUrl": "https://meusite.com/webhooks/cartao",
  "onboardingWebhookUrl": "https://meusite.com/webhooks/onboarding"
}

​

Atualizar Configuração

curl --request PATCH \
  --url https://api-gateway.firebanking.com.br/business/webhook \
  --header 'Content-Type: application/json' \
  --header 'apiKey: sua_chave_api' \
  --data '{
    "pixWebhookUrl": "https://novosite.com/webhooks/pix"
  }'

​

Códigos de Resposta

​

Remover Webhook

curl --request DELETE \
  --url https://api-gateway.firebanking.com.br/business/webhook/pix \
  --header 'apiKey: sua_chave_api'

​

Monitoramento e Debug

​

Logs de Webhook

• Histórico completo de webhooks enviados
• Status de entrega e tentativas de retry
• Payload completo enviado
• Resposta recebida da aplicação

​

Webhook de Teste

• Simule diferentes tipos de eventos
• Valide o tratamento de erros
• Teste o retry automático

​

Boas Práticas

​

Webhooks por Produto

​

PIX Cash In e Cash Out

• Cobranças recebidas: Quando clientes pagam via PIX
• Saques processados: Para transferências PIX de saída
• Expiração de cobranças: QR Codes que expiraram
• Falhas de saque: Quando há problemas no processamento

{
  "event": "pix.charge.paid",
  "transaction_id": "pix_123456789",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "amount": 50.00,
    "payer": {
      "name": "João Silva",
      "document": "***.***.***-**"
    }
  }
}

​

Boleto Bancário

• Confirmações de pagamento: Quando boletos são pagos
• Vencimentos: Notificação de boletos vencidos
• Cancelamentos: Boletos cancelados pelo cliente ou sistema

{
  "event": "bankslip.paid",
  "transaction_id": "boleto_987654321",
  "timestamp": "2024-01-15T14:20:00Z",
  "data": {
    "amount": 150.00,
    "paid_at": "2024-01-15T14:15:00Z",
    "bank": "001"
  }
}

​

Cartão de Crédito

• Autorizações: Pagamentos pré-autorizados
• Capturas: Valores efetivamente cobrados
• Estornos: Processamento de reembolsos
• Falhas: Cartões negados ou problemas técnicos

{
  "event": "payment.captured",
  "transaction_id": "card_555666777",
  "timestamp": "2024-01-15T16:45:00Z",
  "data": {
    "amount": 299.90,
    "installments": 3,
    "brand": "visa",
    "last_four": "1234"
  }
}

​

Onboarding (Contas Específicas)

• Início do processo: Novo cliente iniciou onboarding
• Documentos pendentes: Solicitação de documentos adicionais
• Aprovação: Onboarding concluído com sucesso
• Rejeição: Onboarding rejeitado por conformidade

{
  "event": "onboarding.completed",
  "customer_id": "cust_789012345",
  "timestamp": "2024-01-15T18:30:00Z",
  "data": {
    "status": "approved",
    "tier": "premium",
    "activated_products": ["pix", "card", "boleto"]
  }
}

​

Próximos Passos

• Configure Tratamento de Erros para diferentes cenários de webhook
• Explore a API de Webhooks para configuração programática
• Teste sua implementação no ambiente de desenvolvimento