Reenviar Webhooks de Boleto

Visão Geral

Reenvia manualmente os webhooks de atualização de status para boletos que já foram processados. Útil para recuperar notificações perdidas ou testar integrações.

Este endpoint reenvia apenas webhooks de status finais (PAID, WAITING_PAYMENT, CANCELED). Status intermediários como PENDING são ignorados.

Casos de Uso

Webhook perdido: Quando seu servidor não recebeu a notificação original
Retry após downtime: Reprocessar notificações perdidas durante uma manutenção
Teste de integração: Validar tratamento de webhooks sem criar novos boletos
Debug: Reenviar notificação específica para análise

Parâmetros da Requisição

Você pode especificar pagamentos por período OU por lista de IDs. Pelo menos um dos dois métodos deve ser fornecido.

Filtro por Período

startDate

string (ISO 8601)

Data inicial do período de buscaExemplo: 2024-01-01

Obrigatório se endDate for fornecido. Não pode ser usado junto com paymentIds.

endDate

string (ISO 8601)

Data final do período de buscaExemplo: 2024-01-31

Obrigatório se startDate for fornecido. Não pode ser usado junto com paymentIds.

Filtro por IDs

paymentIds

array

Lista de IDs dos pagamentos (UUIDs)Exemplo: ["550e8400-e29b-41d4-a716-446655440000", "6ba7b810-9dad-11d1-80b4-00c04fd430c8"]

Obrigatório se startDate e endDate não forem fornecidos.

Status Processados

Status	Webhook Reenviado?	Motivo
`PAID`	✅ Sim	Status final - pagamento confirmado
`WAITING_PAYMENT`	✅ Sim	Boleto emitido aguardando pagamento
`CANCELED`	✅ Sim	Status final - boleto cancelado
`PENDING`	❌ Não	Status intermediário - sem webhook
`PROVIDER_CREATION_ERROR`	❌ Não	Erro técnico - sem webhook
`PROVIDER_CANCEL_ERROR`	❌ Não	Erro técnico - sem webhook

Resposta de Sucesso

message

string

Mensagem de confirmaçãoValor: "Payment updates sent successfully"

O endpoint retorna sucesso mesmo se alguns webhooks falharem. Verifique os logs para detalhes de falhas individuais.

Exemplo de Requisição

Reenviar por Período

cURL

curl -X POST https://api-gateway.firebanking.com.br/bank-slip/v1/payment/webhooks/resend \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }'

JavaScript

const response = await fetch('https://api-gateway.firebanking.com.br/bank-slip/v1/payment/webhooks/resend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    startDate: '2024-01-01',
    endDate: '2024-01-31'
  })
});

const data = await response.json();

Python

import requests

response = requests.post(
    'https://api-gateway.firebanking.com.br/bank-slip/v1/payment/webhooks/resend',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'startDate': '2024-01-01',
        'endDate': '2024-01-31'
    }
)

data = response.json()

Reenviar por Lista de IDs

cURL

curl -X POST https://api-gateway.firebanking.com.br/bank-slip/v1/payment/webhooks/resend \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "paymentIds": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    ]
  }'

JavaScript

const response = await fetch('https://api-gateway.firebanking.com.br/bank-slip/v1/payment/webhooks/resend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    paymentIds: [
      '550e8400-e29b-41d4-a716-446655440000',
      '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
    ]
  })
});

const data = await response.json();

Python

import requests

response = requests.post(
    'https://api-gateway.firebanking.com.br/bank-slip/v1/payment/webhooks/resend',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'paymentIds': [
            '550e8400-e29b-41d4-a716-446655440000',
            '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
        ]
    }
)

data = response.json()

Exemplo de Resposta

{
  "message": "Payment updates sent successfully"
}

Códigos de Resposta

200

success

Webhooks enviados com sucesso

Alguns webhooks individuais podem ter falhado. Verifique os logs para detalhes.

400

error

Requisição inválidaPossíveis causas:

Nem startDate/endDate nem paymentIds foram fornecidos
startDate fornecido sem endDate (ou vice-versa)
Formato de data inválido

401

error

API key inválida ou ausente

404

error

Nenhum pagamento encontrado com os critérios fornecidos

500

error

Erro interno do servidor

Erros Comuns

Nenhum pagamento encontrado

{
  "statusCode": 404,
  "message": "No payment found to notify update",
  "error": "Not Found"
}

Nenhum pagamento atende aos critérios de busca (período ou IDs).

Parâmetros ausentes

{
  "statusCode": 400,
  "message": "Either startDate/endDate or paymentIds must be provided",
  "error": "Bad Request"
}

Você deve fornecer um dos dois métodos de filtro.

Data incompleta

{
  "statusCode": 400,
  "message": "startDate is required when endDate is provided",
  "error": "Bad Request"
}

Se usar filtro por período, ambas as datas são obrigatórias.

Comportamento e Limitações

Webhooks Reenviados

Para cada status, o webhook contém: PAID (Pagamento Confirmado):

{
  "event": "payment.paid",
  "payment": {
    "id": "uuid",
    "externalId": "external-id",
    "status": "PAID",
    "amount": 150.00,
    "paymentDate": "2024-01-10T14:30:00.000Z",
    "paymentType": "PIX"
  }
}

WAITING_PAYMENT (Aguardando Pagamento):

{
  "event": "payment.waiting",
  "payment": {
    "id": "uuid",
    "externalId": "external-id",
    "status": "WAITING_PAYMENT",
    "pdfUrl": "https://...",
    "pixCode": "00020101021226...",
    "barcode": "34191091000000150001...",
    "slipLine": "34191234567880000..."
  }
}

CANCELED (Cancelado):

{
  "event": "payment.canceled",
  "payment": {
    "id": "uuid",
    "externalId": "external-id",
    "status": "CANCELED",
    "cancelReason": "Requested by user"
  }
}

Falhas e Retries

Importante: O endpoint não garante entrega. Se o webhook URL da conta estiver indisponível, a requisição falhará.

✅ Tentativas são feitas em paralelo (Promise.allSettled)
✅ Falhas individuais são logadas mas não interrompem o processo
✅ Retorna sucesso mesmo se alguns webhooks falharem
❌ Não há retry automático - se falhar, você deve chamar o endpoint novamente

Performance

Para períodos longos (muitos pagamentos), o processo pode demorar
Máximo recomendado: ~100 pagamentos por requisição
Considere filtrar por períodos menores se tiver volume alto

Boas Práticas

Use Períodos Curtos

Filtre por períodos de 7-30 dias para evitar timeout

IDs Específicos

Para reenvios pontuais, use paymentIds ao invés de período

Monitore Logs

Verifique logs da aplicação para detalhes de falhas

Webhook URL Válido

Garanta que seu webhook URL esteja configurado e acessível

Monitoramento

Os logs incluem informações detalhadas:

[ResendPaymentUpdateUseCase][Execute]: Resend completed
{
  businessId: "uuid",
  totalPayments: 25,
  successCount: 23,
  failureCount: 2,
  successRate: "92.00%"
}

Logs de Erro

Para webhooks que falharam:

[ResendPaymentUpdateUseCase][Execute]: Failed to resend notification
{
  paymentId: "uuid",
  externalId: "external-id",
  errorType: "HTTP_ERROR",
  errorStatus: 500,
  errorMessage: "Internal Server Error",
  webhookUrl: "https://your-server.com/webhooks"
}

Próximos Passos

Configurar Webhook URL: Configuração de Webhooks
Emitir Boletos: Criar Boleto
Pagar Boletos: Pagar Boleto
Consultar Status: Listar Pagamentos

Dica de Debug: Use este endpoint em ambiente de testes para validar seu sistema de recebimento de webhooks antes do go-live.

Visão Geral

Fluxo de Integração

Emissão de Boletos

Pagamento de Boletos

Gestão

Webhooks

Visão Geral

Casos de Uso

Parâmetros da Requisição

Filtro por Período

Filtro por IDs

Status Processados

Resposta de Sucesso

Exemplo de Requisição

Reenviar por Período

Reenviar por Lista de IDs

Exemplo de Resposta

Códigos de Resposta

Erros Comuns

Comportamento e Limitações

Webhooks Reenviados

Falhas e Retries

Performance

Boas Práticas

Use Períodos Curtos

IDs Específicos

Monitore Logs

Webhook URL Válido

Monitoramento

Logs de Erro

Próximos Passos

Visão Geral

Fluxo de Integração

Emissão de Boletos

Pagamento de Boletos

Gestão

Webhooks

​Visão Geral

​Casos de Uso

​Parâmetros da Requisição

​Filtro por Período

​Filtro por IDs

​Status Processados

​Resposta de Sucesso

​Exemplo de Requisição

​Reenviar por Período

​Reenviar por Lista de IDs

​Exemplo de Resposta

​Códigos de Resposta

​Erros Comuns

​Comportamento e Limitações

​Webhooks Reenviados

​Falhas e Retries

​Performance

​Boas Práticas

Use Períodos Curtos

IDs Específicos

Monitore Logs

Webhook URL Válido

​Monitoramento

​Logs de Erro

​Próximos Passos

Visão Geral

Casos de Uso

Parâmetros da Requisição

Filtro por Período

Filtro por IDs

Status Processados

Resposta de Sucesso

Exemplo de Requisição

Reenviar por Período

Reenviar por Lista de IDs

Exemplo de Resposta

Códigos de Resposta

Erros Comuns

Comportamento e Limitações

Webhooks Reenviados

Falhas e Retries

Performance

Boas Práticas

Monitoramento

Logs de Erro

Próximos Passos