Webhooks

Os webhooks da FastPay permitem que sua aplicação receba notificações em tempo real sobre mudanças no status das transações, eliminando a necessidade de polling constante da API.

Como funcionam

Quando um evento importante acontece (como uma cobrança sendo paga), a FastPay envia automaticamente uma requisição HTTP POST para a URL que você configurou, contendo todos os detalhes do evento.

Configuração

Os webhooks podem ser configurados de duas formas:

1. Via Painel da FastPay

No painel da FastPay, navegue até: Configurações > Webhooks > Criar Webhook

Informe a URL onde deseja receber as notificações.

2. Via API (campo postbackUrl)

Alternativamente, você pode configurar o webhook diretamente no momento da criação da cobrança, informando a URL no campo postbackUrl:

{
  "amount": 100,
  "currency": "BRL",
  "postbackUrl": "https://meusite.com/webhooks/fastpay",
  "customer": {
    // ... dados do cliente
  }
}

Estrutura do Payload

Todos os webhooks seguem esta estrutura:

{
  "id": "webhook_event_id",
  "event": "charge.paid",
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    // Objeto completo da cobrança
  }
}

Tipos de Eventos

Evento	Descrição
charge.created	📝 Enviado quando uma nova cobrança é criada
charge.pending	⏳ Enviado quando uma cobrança está aguardando pagamento
charge.paid	💰 Enviado quando uma cobrança é paga com sucesso
charge.updated	🔄 Enviado quando qualquer campo da cobrança é atualizado

Implementação

Endpoint básico

Seu endpoint deve:

1. Aceitar POST requests na URL configurada
2. Responder com status 200 para confirmar o recebimento
3. Processar rapidamente (timeout padrão)
4. Tratar dados JSON enviados no body da requisição

Segurança e Boas Práticas

Validação de origem

Para garantir que o webhook veio realmente da FastPay:

1. Verifique o IP de origem (fornecemos uma lista de IPs confiáveis)
2. Use HTTPS sempre que possível
3. Implemente rate limiting no seu endpoint

Idempotência

Webhooks podem ser enviados mais de uma vez. Use o campo id para evitar processamento duplicado:

const processedEvents = new Set();

app.post('/webhooks/fastpay', (req, res) => {
  const { id, event, data } = req.body;
  
  // Verificar se já processamos este evento
  if (processedEvents.has(id)) {
    return res.status(200).send('Already processed');
  }
  
  // Processar evento...
  
  // Marcar como processado
  processedEvents.add(id);
  res.status(200).send('OK');
});

Tratamento de erros

Se seu endpoint retornar um erro (status diferente de 2xx), a FastPay tentará reenviar:

• Tentativa 1: Imediatamente
• Tentativa 2: Após 1 minuto
• Tentativa 3: Após 5 minutos
• Tentativa 4: Após 15 minutos
• Tentativa 5: Após 1 hora

Após 5 tentativas falhadas, o webhook é marcado como "failed" no painel.

Testando Webhooks

Ferramentas úteis

1. ngrok - Para expor localhost na internet durante desenvolvimento
2. webhook.site - Para inspecionar payloads durante testes
3. Postman - Para simular webhooks manualmente

Exemplo com ngrok

# Instalar ngrok
npm install -g ngrok

# Expor porta local
ngrok http 3000

# Usar a URL gerada (ex: https://abc123.ngrok.io/webhooks/fastpay)

Monitoramento

No painel da FastPay, você pode:

• Ver histórico de webhooks enviados
• Reenviar webhooks falhados manualmente
• Verificar logs de entrega
• Testar endpoints com payloads de exemplo

Troubleshooting

Webhook não está sendo recebido

1. Verifique se a URL está correta e acessível
2. Confirme que seu servidor responde com status 200
3. Verifique logs no painel da FastPay
4. Teste a URL manualmente com cURL

Múltiplos webhooks para o mesmo evento

Isso pode acontecer em caso de:

• Timeout no seu endpoint
• Resposta com status diferente de 2xx
• Problemas temporários de rede

Solução: Implemente idempotência usando o campo id.