Pular para o conteúdo principal

​
Visão Geral

Os webhooks de cartão de crédito permitem que sua aplicação receba notificações em tempo real sobre mudanças no status das transações, garantindo sincronização automática entre os sistemas.

​
Status dos Webhooks

O webhook é disparado sempre que uma cobrança pontual ou assinatura sofrer alguma modificação de status. O servidor deve retornar código 200 para confirmar o recebimento. Outros códigos resultarão no reenvio da mensagem.

​
Status Disponíveis

  • PAID - Pagamento aprovado e processado com sucesso
  • DENIED - Pagamento negado (cartão recusado, saldo insuficiente, etc.)
  • CANCELED - Pagamento cancelado
  • REFUNDED - Pagamento estornado

​
Estrutura do Payload

​
Payload do Webhook

Pagamento Aprovado (Status: PAID)
{
  "product": "CREDIT_CARD",
  "paymentId": "070ab63a-5849-4f1b-ad10-a67b9136711f",
  "externalId": "b8775b66-bbed-45ec-a0da-a31a39e7e5bf",
  "status": "PAID",
  "processedAt": "2025-07-31T19:31:02.737Z",
  "additionalInfo": {
    "purchaseTitle": "Compra avulsa",
    "description": "Descrição da compra para teste",
    "amount": 100.0,
    "installments": 1,
    "chargeType": "FEE_TO_SELLER",
    "cardBrand": "mastercard",
    "cardLastDigits": "5601",
    "metadata": {
      "orderId": "internal-123321",
      "customerId": "cust-123321"
    }
  }
}
Pagamento Negado (Status: DENIED)
{
  "product": "CREDIT_CARD",
  "paymentId": "070ab63a-5849-4f1b-ad10-a67b9136711f",
  "externalId": "b8775b66-bbed-45ec-a0da-a31a39e7e5bf",
  "status": "DENIED",
  "processedAt": "2025-07-31T19:31:02.737Z",
  "additionalInfo": {
    "purchaseTitle": "Compra avulsa",
    "description": "Descrição da compra para teste",
    "amount": 100.0,
    "installments": 1,
    "chargeType": "FEE_TO_SELLER",
    "cardBrand": "mastercard",
    "cardLastDigits": "5601",
    "denialReason": "Insufficient funds",
    "metadata": {
      "orderId": "internal-123321",
      "customerId": "cust-123321"
    }
  }
}
Pagamento Estornado (Status: REFUNDED)
{
  "product": "CREDIT_CARD",
  "paymentId": "070ab63a-5849-4f1b-ad10-a67b9136711f",
  "externalId": "b8775b66-bbed-45ec-a0da-a31a39e7e5bf",
  "status": "REFUNDED",
  "processedAt": "2025-07-31T19:31:02.737Z",
  "additionalInfo": {
    "purchaseTitle": "Compra avulsa",
    "description": "Descrição da compra para teste",
    "amount": 100.0,
    "refundAmount": 100.0,
    "installments": 1,
    "chargeType": "FEE_TO_SELLER",
    "cardBrand": "mastercard",
    "cardLastDigits": "5601",
    "metadata": {
      "orderId": "internal-123321",
      "customerId": "cust-123321"
    }
  }
}

​
Configuração

Configure a URL do webhook de cartão de crédito através do endpoint de configuração de conta:
cURL
curl --request POST \
  --url https://api-gateway.firebanking.com.br/v1/account/webhook \
  --header 'x-api-key: sua_chave_api' \
  --header 'Content-Type: application/json' \
  --data '{
    "creditCardWebhookUrl": "https://meusite.com.br/webhooks/cartao"
  }'
Para configuração completa de webhooks, acesse a documentação de configuração.

​
Validação de Segurança

​
Verificação de Assinatura

Sempre valide a assinatura do webhook para garantir autenticidade: 
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)

# Uso

is_valid = verify_webhook_signature(
request.body,
request.headers['X-FireBanking-Signature'],
webhook_secret
)

​
Implementação Robusta

​
Tratamento de Resposta

Sua aplicação deve responder adequadamente aos webhooks: 
HTTP/1.1 200 OK
Content-Length: 0
  • Status 200-299: Webhook processado com sucesso
  • Outros status: FireBanking tentará reenviar

​
Retry Policy

O FireBanking implementa retry automático:
  • Tentativas: Até 5 tentativas com backoff exponencial
  • Intervalo: 1s, 3s, 9s, 27s, 81s
  • Timeout: 30 segundos por tentativa

​
Idempotência

Implemente controle de idempotência usando o transaction_id: 
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"

​
Exemplo Prático

​
Manipulador Express.js

const express = require("express");
const crypto = require("crypto");
const app = express();

app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/credit-card", (req, res) => {
  const signature = req.headers["x-firebanking-signature"];
  const payload = req.body;

  // Verifica assinatura
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(payload);

  switch (event.event) {
    case "payment.captured":
      console.log("Pagamento capturado:", event.data.id);
      // Atualizar status no seu sistema
      updatePaymentStatus(event.data.id, "captured");
      break;

    case "payment.failed":
      console.log("Pagamento falhou:", event.data.id);
      // Notificar cliente sobre falha
      notifyPaymentFailure(event.data.buyer.email);
      break;

    case "subscription.payment_successful":
      console.log(
        "Cobrança recorrente bem-sucedida:",
        event.data.subscription_id
      );
      // Renovar acesso do usuário
      renewUserAccess(event.data.buyer.email);
      break;

    default:
      console.log("Evento desconhecido:", event.event);
  }

  res.status(200).send("OK");
});

​
Monitoramento

​
Dashboard

Monitore seus webhooks em tempo real através do Dashboard FireBanking:
  • Histórico completo de webhooks enviados
  • Status de entrega e tentativas de retry
  • Payload completo enviado
  • Resposta recebida da aplicação

​
Logs Recomendados

{
  "timestamp": "2024-01-15T10:30:00Z",
  "event": "webhook_received",
  "webhook_id": "wh_123456",
  "event_type": "payment.captured",
  "transaction_id": "fb_trans_123456789",
  "status": "processed",
  "processing_time_ms": 150
}

​
Próximos Passos

Dica: Use ferramentas como webhook.site para testar e depurar seus webhooks durante o desenvolvimento.