Pular para o conteúdo principal

​
Visão Geral

O endpoint de Reenvio de Webhook permite que você solicite o reenvio manual de notificações de transações específicas. Isso é útil em cenários onde:
  • Seu servidor estava indisponível quando o webhook original foi enviado
  • Você precisa reprocessar uma transação específica
  • Deseja testar a integração com uma URL diferente temporariamente
Este endpoint não altera a configuração de webhook da sua conta. A URL fornecida é usada apenas para o reenvio específico.

​
Funcionamento

​
Identificação da Transação

O endpoint aceita três tipos de identificadores:
TipoDescriçãoEscopo
ID NuméricoID interno da transação (campo transactionId nos webhooks)Global
ID ExternoIdentificador fornecido por você na criação (campo externalId)Único por conta
End-to-End IDIdentificador PIX do BACEN (campo endToEndId, formato: E/D + 32 chars)Único por transação
O sistema busca simultaneamente por todos os tipos de identificador na sua conta. Na prática não há ambiguidade: id numérico é puramente dígitos; e2eId começa com ‘E’ ou ‘D’ seguido de 32 caracteres alfanuméricos; externalId é qualquer string fornecida por você.
Qual identificador usar? Use o transactionId numérico retornado pela Forge, o externalId que você forneceu na criação da transação, ou o endToEndId do PIX recebido nos webhooks. Todos são igualmente válidos.

​
Processamento Síncrono

O reenvio de webhook é processado de forma síncrona. Isso significa que:
  • A requisição aguarda o envio do webhook ser concluído
  • O resultado é comunicado via HTTP status code (200, 502, 504)
  • O tempo de resposta depende da latência do seu servidor (timeout: 10s)
Diferentemente dos webhooks automáticos (que utilizam filas com retry), o reenvio manual é executado imediatamente e retorna o resultado na mesma requisição.

​
Casos de Uso

​
1. Reenvio para URL Configurada

Se você já tem um webhook configurado na sua conta, basta chamar o endpoint sem body: 
curl -X POST https://api.gateway.goforge.com.br/api/resend-webhook/external-teste-001 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

​
2. Reenvio com URL Temporária

Para testar com uma URL diferente ou reenviar para um endpoint de contingência: 
curl -X POST https://api.gateway.goforge.com.br/api/resend-webhook/external-teste-001 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-servidor-backup.com/webhooks/goforge"
  }'
A URL temporária não é persistida. O próximo webhook automático será enviado para a URL configurada na conta.

​
Resposta

​
Sucesso (200)

Webhook enviado com sucesso para a URL de destino. 
{
  "message": "Webhook resent successfully",
  "webhookLogId": 12345,
  "sentAt": "2024-01-15T10:30:00.000Z",
  "statusCode": 200
}

​
Erro: Sem URL Configurada (400)

{
  "statusCode": 400,
  "message": "No webhook configured and no override URL provided",
  "error": "Bad Request"
}

​
Erro: Transação Não Encontrada (404)

{
  "statusCode": 404,
  "message": "Transaction not found",
  "error": "Not Found"
}

​
Erro: Destino Retornou Erro (502)

O servidor de destino retornou um erro (4xx ou 5xx) ou houve falha de conexão. 
{
  "statusCode": 502,
  "message": "Webhook failed with status 500",
  "webhookLogId": 12345,
  "sentAt": "2024-01-15T10:30:00.000Z"
}
Mesmo em caso de erro, o webhook é registrado no log de auditoria. Use o webhookLogId para rastreamento.

​
Erro: Timeout (504)

O servidor de destino não respondeu dentro do tempo limite (10 segundos). 
{
  "statusCode": 504,
  "message": "Timeout after 10000ms",
  "webhookLogId": 12345,
  "sentAt": "2024-01-15T10:30:00.000Z"
}
Se você está recebendo timeouts frequentes, verifique se seu servidor está respondendo em menos de 10 segundos.

​
Rate Limiting

Este endpoint possui rate limiting de 60 requisições por minuto por conta para evitar abusos.
Se o limite for excedido, você receberá um erro 429 Too Many Requests: 
{
  "statusCode": 429,
  "message": "Too Many Requests"
}

​
Auditoria

Todos os reenvios manuais são registrados para fins de auditoria e rastreabilidade:
InformaçãoDescrição
Tipo de envioMarcado como reenvio manual
URL utilizadaRegistra se foi usada URL temporária ou configurada
ResultadoStatus HTTP e tempo de resposta
IdentificadorID único do log para rastreamento
Use o webhookLogId retornado na resposta para correlacionar com logs de suporte se necessário.

​
Exemplos de Integração

const axios = require('axios');

async function resendWebhook(transactionId, overrideUrl = null) {
  const config = {
    headers: {
      'Authorization': `Bearer ${process.env.FORGE_TOKEN}`,
      'Content-Type': 'application/json'
    }
  };

  const body = overrideUrl ? { url: overrideUrl } : {};

  try {
    const response = await axios.post(
      `https://api.gateway.goforge.com.br/api/resend-webhook/${transactionId}`,
      body,
      config
    );

    console.log('Webhook reenviado:', response.data);
    return response.data;
  } catch (error) {
    console.error('Erro ao reenviar webhook:', error.response?.data);
    throw error;
  }
}

// Uso
resendWebhook('external-teste-001');
resendWebhook('external-teste-001', 'https://backup.meusite.com/webhook'); // Com URL temporária

​
Próximos Passos

Visão Geral de Webhooks

Entenda como os webhooks funcionam na Forge

Implementação

Guia completo de implementação de webhooks