Configurar URLs de Webhook - Documentação da API FireBanking

Configure URLs de webhook para receber notificações automáticas sobre eventos em sua conta FireBanking. Este endpoint permite definir endpoints específicos para diferentes tipos de notificações.

Tipos de Webhook

PIX Webhook

pixWebhookUrl Notificações de transações PIX (recebimento e envio)

Boleto Webhook

bankSlipWebhookUrl Atualizações de status de boletos bancários

Cartão Webhook

creditCardWebhookUrl Notificações de transações de cartão de crédito

Onboarding Webhook

onboardingWebhookUrl Atualizações do processo de cadastro e KYC

Exemplo de Requisição

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 '{
    "pixWebhookUrl": "https://meusite.com.br/webhooks/pix",
    "bankSlipWebhookUrl": "https://meusite.com.br/webhooks/boleto",
    "creditCardWebhookUrl": "https://meusite.com.br/webhooks/cartao",
    "onboardingWebhookUrl": "https://meusite.com.br/webhooks/onboarding"
  }'

Parâmetros da Requisição

pixWebhookUrl

string

URL para receber notificações de transações PIX

bankSlipWebhookUrl

string

URL para receber notificações de boletos bancários

creditCardWebhookUrl

string

URL para receber notificações de cartão de crédito

onboardingWebhookUrl

string

URL para receber notificações do processo de onboarding

Exemplo de Resposta

Resposta de Sucesso

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

Campos da Resposta

pixWebhookUrl

string

required

URL configurada para webhooks de PIX

bankSlipWebhookUrl

string

required

URL configurada para webhooks de boleto

creditCardWebhookUrl

string

required

URL configurada para webhooks de cartão

onboardingWebhookUrl

string

required

URL configurada para webhooks de onboarding

Requisitos de Webhook

Requisitos Técnicos

HTTPS Obrigatório

TLS 1.2+ Todas as URLs devem usar HTTPS com certificado válido

Resposta HTTP

200-299 Responder com status 2xx em até 30 segundos

Idempotência

Mesmo Evento Processar o mesmo evento múltiplas vezes sem efeitos colaterais

Timeout

30 segundos Webhook deve responder dentro do timeout

Configuração Atualizada

Configurar URLs Individualmente

{
  "pixWebhookUrl": "https://meusite.com.br/pix"
}

Limpar URL de Webhook

{
  "pixWebhookUrl": ""
}

Eventos de Webhook

PIX Webhook

Eventos enviados para pixWebhookUrl:

Evento	Descrição
`pix.received`	PIX recebido na conta
`pix.sent`	PIX enviado confirmado
`pix.failed`	PIX rejeitado ou falhou
`pix.refunded`	PIX estornado

Boleto Webhook

Eventos enviados para bankSlipWebhookUrl:

Evento	Descrição
`bankslip.paid`	Boleto pago
`bankslip.expired`	Boleto vencido
`bankslip.cancelled`	Boleto cancelado

Cartão Webhook

Eventos enviados para creditCardWebhookUrl:

Evento	Descrição
`card.authorized`	Transação autorizada
`card.captured`	Transação capturada
`card.failed`	Transação negada
`card.refunded`	Transação estornada

Onboarding Webhook

Eventos enviados para onboardingWebhookUrl:

Evento	Descrição
`kyc.approved`	KYC aprovado
`kyc.rejected`	KYC rejeitado
`account.activated`	Conta ativada

Estrutura do Payload

Cabeçalhos

POST /seu-webhook-endpoint
Content-Type: application/json
X-Fire-Event: pix.received
X-Fire-Signature: sha256=hash_hmac
X-Fire-Timestamp: 1640995200

Payload Padrão

{
  "event": "pix.received",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "data": {
    "id": "tx_123456789",
    "amount": 100.50,
    "status": "completed",
    "metadata": {...}
  }
}

Segurança

Verificação de Assinatura

Sempre verifique a assinatura do webhook:

Python

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return signature === `sha256=${expected}`;
}

Monitoramento

Tentativas e Retry

Tentativas

5 tentativas Com backoff exponencial

Timeout

30 segundos Tempo limite por tentativa

Status

Dashboard Monitore entregas no painel

Logs de Webhook

Acesse logs detalhados no painel administrativo:

Status de entrega
Tempo de resposta
Conteúdo dos payloads
Códigos de erro

Casos de Uso

Conciliação Automática

Atualizar sistema interno automaticamente quando PIX é recebido

Notificações

Enviar SMS/email para clientes sobre mudanças de status

Integração ERP

Sincronizar dados financeiros com sistema de gestão

Relatórios

Gerar relatórios automáticos de transações

Códigos de Resposta

Código	Descrição	Solução
200	Sucesso	URLs configuradas
400	URL inválida	Verifique formato das URLs
401	Não autorizado	Verifique header `x-api-key`
403	Proibido	Chave API sem permissões
500	Erro interno	Tente novamente

URLs inválidas ou inacessíveis serão rejeitadas. Certifique-se de que os endpoints estão funcionando antes de configurar.

Testando Webhooks

Webhook de Teste

Use ferramentas como ngrok para testar localmente:

Terminal

# Expor localhost:3000
ngrok http 3000

# Configurar webhook de teste
curl -X POST https://api-gateway.firebanking.com.br/v1/account/webhook \
  -H 'x-api-key: sua_chave_api' \
  -d '{"pixWebhookUrl": "https://abc123.ngrok.io/webhook"}'

Endpoint de Teste

Express.js

app.post('/webhook', (req, res) => {
  console.log('Webhook recebido:', req.body);
  console.log('Headers:', req.headers);

  // Processar evento
  const { event, data } = req.body;

  // Responder rapidamente
  res.status(200).json({ received: true });
});

Próximos Passos

Implemente verificação de assinatura para segurança
Configure logs e monitoramento para observabilidade
Teste diferentes cenários de webhook
Monitore métricas de entrega no dashboard

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Body

application/json

pixWebhookUrl

string<uri>

URL para receber notificações de transações PIX

Example:

"https://meusite.com.br/webhooks/pix"

bankSlipWebhookUrl

string<uri>

URL para receber notificações de boletos bancários

Example:

"https://meusite.com.br/webhooks/boleto"

creditCardWebhookUrl

string<uri>

URL para receber notificações de cartão de crédito

Example:

"https://meusite.com.br/webhooks/cartao"

onboardingWebhookUrl

string<uri>

URL para receber notificações do processo de onboarding

Example:

"https://meusite.com.br/webhooks/onboarding"

Response

URLs de webhook configuradas com sucesso

pixWebhookUrl

string

required

URL configurada para webhooks de PIX

Example:

"https://meusite.com.br/webhooks/pix"

bankSlipWebhookUrl

string

required

URL configurada para webhooks de boleto

Example:

"https://meusite.com.br/webhooks/boleto"

creditCardWebhookUrl

string

required

URL configurada para webhooks de cartão

Example:

"https://meusite.com.br/webhooks/cartao"

onboardingWebhookUrl

string

required

URL configurada para webhooks de onboarding

Example:

"https://meusite.com.br/webhooks/onboarding"

Visão Geral

Conta

Webhooks

​Tipos de Webhook

PIX Webhook

Boleto Webhook

Cartão Webhook

Onboarding Webhook

​Exemplo de Requisição

​Parâmetros da Requisição

​Exemplo de Resposta

​Campos da Resposta

​Requisitos de Webhook

​Requisitos Técnicos

HTTPS Obrigatório

Resposta HTTP

Idempotência

Timeout

​Configuração Atualizada

​Eventos de Webhook

​PIX Webhook

​Boleto Webhook

​Cartão Webhook

​Onboarding Webhook

​Estrutura do Payload

​Cabeçalhos

​Payload Padrão

​Segurança

​Verificação de Assinatura

​Monitoramento

​Tentativas e Retry

Tentativas

Timeout

Status

​Logs de Webhook

​Casos de Uso

Conciliação Automática

Notificações

Integração ERP

Relatórios

​Códigos de Resposta

​Testando Webhooks

​Webhook de Teste

​Endpoint de Teste

​Próximos Passos

Authorizations

Body

Response

Tipos de Webhook

Exemplo de Requisição

Parâmetros da Requisição

Exemplo de Resposta

Campos da Resposta

Requisitos de Webhook

Requisitos Técnicos

Configuração Atualizada

Eventos de Webhook

PIX Webhook

Boleto Webhook

Cartão Webhook

Onboarding Webhook

Estrutura do Payload

Cabeçalhos

Payload Padrão

Segurança

Verificação de Assinatura

Monitoramento

Tentativas e Retry

Logs de Webhook

Casos de Uso

Códigos de Resposta

Testando Webhooks

Webhook de Teste

Endpoint de Teste

Próximos Passos