Reenviar Webhook PIX

Visão Geral

Reenvia manualmente o webhook de uma transação PIX específica. Útil para recuperar notificações perdidas ou testar integrações.

Rate Limit: Este endpoint possui rate limiting de 60 requisições por minuto para prevenir sobrecarga.

Casos de Uso

Webhook perdido: Quando seu servidor não recebeu a notificação original
Retry após downtime: Reprocessar notificação perdida durante manutenção
Teste de integração: Validar tratamento de webhooks com transações reais
Debug: Reenviar notificação específica para análise de payload

Parâmetros da Requisição

Path Parameters

transactionId

string

required

ID da transação PIX (UUID ou MongoDB ObjectId)Exemplo: 507f1f77bcf86cd799439011 ou 550e8400-e29b-41d4-a716-446655440000

Body Parameters

url

string (URL)

URL alternativa para enviar o webhook (opcional)Validação: Deve ser uma URL válida usando protocolo HTTPSExemplo: https://webhook.seuservidor.com/pix/callback

Se não fornecido, usa a URL configurada na conta:

callbackWebhookUrl da transação
pixWebhookUrl da conta
webhookUrl global da conta

Resposta de Sucesso

Success

boolean

Indica se o webhook foi reenviado com sucessoValor: true

Estrutura do Webhook

O webhook reenviado segue a estrutura padrão V1:

{
  "transactionId": "507f1f77bcf86cd799439011",
  "businessTransactionId": "external-id-123",
  "status": "PAID",
  "value": 150.00,
  "movementType": "IN",
  "endToEndId": "E12345678202401101430000000001",
  "pixKey": "[email protected]",
  "createdDate": "2024-01-10T14:30:00.000Z",
  "PayerName": "João Silva",
  "PayerDocumentNumber": "12345678901",
  "PayerBankName": "Banco do Brasil",
  "PayerBankISPB": "00000000",
  "PayerBankBranch": "1234",
  "PayerBankCode": "001",
  "PayerBankAccount": "56789-0",
  "ReceiverName": "Empresa LTDA",
  "ReceiverDocumentNumber": "12345678000190",
  "ReceiverBankName": "Celcoin",
  "ReceiverBankISPB": "00360305",
  "ReceiverBankBranch": "0001",
  "ReceiverBankCode": "329",
  "ReceiverBankAccount": "12345-6"
}

Exemplo de Requisição

Reenviar para URL Padrão

cURL

curl -X POST https://api-gateway.firebanking.com.br/pix/v1/webhooks/resend/507f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://api-gateway.firebanking.com.br/pix/v1/webhooks/resend/507f1f77bcf86cd799439011', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();

Python

import requests

response = requests.post(
    'https://api-gateway.firebanking.com.br/pix/v1/webhooks/resend/507f1f77bcf86cd799439011',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    }
)

data = response.json()

Reenviar para URL Customizada

cURL

curl -X POST https://api-gateway.firebanking.com.br/pix/v1/webhooks/resend/507f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://webhook-test.seuservidor.com/pix"
  }'

JavaScript

const response = await fetch('https://api-gateway.firebanking.com.br/pix/v1/webhooks/resend/507f1f77bcf86cd799439011', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    url: 'https://webhook-test.seuservidor.com/pix'
  })
});

const data = await response.json();

Python

import requests

response = requests.post(
    'https://api-gateway.firebanking.com.br/pix/v1/webhooks/resend/507f1f77bcf86cd799439011',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'url': 'https://webhook-test.seuservidor.com/pix'
    }
)

data = response.json()

Exemplo de Resposta

{
  "Success": true
}

Códigos de Resposta

200

success

Webhook reenviado com sucesso

400

error

Requisição inválidaPossíveis causas:

Transaction ID ausente
URL fornecida não usa HTTPS
Tentativa de reenviar webhook de outra conta (sem permissão)
Conta sem configuração de webhook e URL não fornecida

401

error

API key inválida ou ausente

404

error

Transação não encontrada ou conta não encontrada

429

error

Rate limit excedido (máximo 60 requisições por minuto)

500

error

Erro interno do servidor

Erros Comuns

Transação não encontrada

{
  "statusCode": 404,
  "message": "Transaction with ID 507f1f77bcf86cd799439011 not found",
  "error": "Not Found"
}

O ID da transação fornecido não existe no sistema.

URL não usa HTTPS

{
  "statusCode": 400,
  "message": "url needs to be a valid URL and use HTTPS protocol",
  "error": "Bad Request"
}

A URL customizada fornecida deve usar o protocolo HTTPS obrigatoriamente.

Sem permissão para transação

{
  "statusCode": 400,
  "message": "Cannot resend webhook for this transaction",
  "error": "Bad Request"
}

Você não tem permissão para reenviar webhook desta transação (pertence a outra conta).

Webhook não configurado

{
  "statusCode": 400,
  "message": "Account does not have webhook configuration or url provided",
  "error": "Bad Request"
}

A conta não possui webhook configurado e nenhuma URL foi fornecida no body.

Rate limit excedido

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "Too Many Requests"
}

Você excedeu o limite de 60 requisições por minuto. Aguarde antes de tentar novamente.

Comportamento e Validações

Segurança

Autenticação

Requer x-api-key válida

Autorização

Apenas transações da sua conta

IP Allowlist

Valida IP contra lista permitida

Rate Limiting

Máximo 60 req/min por conta

Prioridade de URL de Webhook

O sistema usa a seguinte ordem de prioridade para determinar a URL do webhook:

URL fornecida no body (parâmetro url)
URL da transação (callbackWebhookUrl)
URL PIX da conta (pixWebhookUrl)
URL global da conta (webhookUrl)

Se nenhuma das opções acima estiver disponível, o endpoint retornará erro 400.

Status Suportados

O endpoint reenvia webhooks para todos os status de transação PIX:

Status	Descrição
`PAID`	Pagamento confirmado (Cash In)
`PENDING`	Aguardando confirmação
`CANCELED`	Transação cancelada
`REFUND`	Estorno processado
`REFUND_IN`	Estorno recebido
`REFUND_OUT`	Estorno enviado

Status de refund (REFUND_IN, REFUND_OUT) são normalizados para REFUND no webhook.

Dados Enviados

O webhook inclui automaticamente:

Informações da transação: ID, status, valor, endToEndId
Dados do pagador (se disponível): Nome, documento, banco, agência, conta
Dados do recebedor (se disponível): Nome, documento, banco, agência, conta
Chave PIX: Recuperada da transação, histórico Celcoin ou conta

Rate Limiting

Limite: 60 requisições por minuto por contaTTL: 60 segundos

Se você precisar reenviar múltiplos webhooks em grande volume:

Envie até 60 requisições por minuto
Para volumes maiores, distribua as requisições ao longo do tempo
Considere usar ferramentas de retry com exponential backoff
Para volumes muito grandes, entre em contato com o suporte

Versões Suportadas

Este endpoint está disponível nas versões:

✅ v1 (atual)
✅ v2 (atual)

Ambas as versões possuem comportamento idêntico.

Próximos Passos

Configurar Webhook: Setup de Webhooks
Criar Cobrança PIX: Criar QR Code
Consultar Transação: Consultar Cobrança
Entender Webhooks: Webhooks Cash In

Boas Práticas

Idempotência

Seguro reenviar múltiplas vezes - use com tranquilidade

URL de Teste

Use parâmetro url para testar em ambientes não-produção

Logs

Monitore logs do seu servidor para debugar recebimento

Respeite Rate Limit

Máximo 60 requisições por minuto

Debug de Integração: Use ferramentas como webhook.site ou requestbin.com para inspecionar o payload sem configurar um servidor.

Endpoint Interno: Existe também um endpoint /internal/resend/:transactionId para uso administrativo com autenticação básica, não documentado para clientes externos.

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

Visão Geral

Casos de Uso

Parâmetros da Requisição

Path Parameters

Body Parameters

Resposta de Sucesso

Estrutura do Webhook

Exemplo de Requisição

Reenviar para URL Padrão

Reenviar para URL Customizada

Exemplo de Resposta

Códigos de Resposta

Erros Comuns

Comportamento e Validações

Segurança

Autenticação

Autorização

IP Allowlist

Rate Limiting

Prioridade de URL de Webhook

Status Suportados

Dados Enviados

Rate Limiting

Versões Suportadas

Próximos Passos

Boas Práticas

Idempotência

URL de Teste

Logs

Respeite Rate Limit

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

​Visão Geral

​Casos de Uso

​Parâmetros da Requisição

​Path Parameters

​Body Parameters

​Resposta de Sucesso

​Estrutura do Webhook

​Exemplo de Requisição

​Reenviar para URL Padrão

​Reenviar para URL Customizada

​Exemplo de Resposta

​Códigos de Resposta

​Erros Comuns

​Comportamento e Validações

​Segurança

Autenticação

Autorização

IP Allowlist

Rate Limiting

​Prioridade de URL de Webhook

​Status Suportados

​Dados Enviados

​Rate Limiting

​Versões Suportadas

​Próximos Passos

​Boas Práticas

Idempotência

URL de Teste

Logs

Respeite Rate Limit

Visão Geral

Casos de Uso

Parâmetros da Requisição

Path Parameters

Body Parameters

Resposta de Sucesso

Estrutura do Webhook

Exemplo de Requisição

Reenviar para URL Padrão

Reenviar para URL Customizada

Exemplo de Resposta

Códigos de Resposta

Erros Comuns

Comportamento e Validações

Segurança

Prioridade de URL de Webhook

Status Suportados

Dados Enviados

Rate Limiting

Versões Suportadas

Próximos Passos

Boas Práticas