🔔 Webhooks

Os Webhooks são notificações automáticas enviadas pela FastGivr via POST HTTPS para o seu servidor sempre que ocorre uma alteração de status em suas cobranças ou saques. Eles eliminam a necessidade de consultar repetidamente a API (polling), economizando processamento e banda.

---

📡 Lista de Eventos Disponíveis

Ao cadastrar uma URL de webhook no painel administrativo, você pode escolher escutar os seguintes eventos:

Nome do Evento	Gatilho de Disparo	Ação Recomendada
charge.paid	Pagamento confirmado com sucesso (Pix, Cartão, Boleto).	Liberar serviço / Despachar produto.
charge.failed	Transação recusada ou boleto vencido sem pagamento.	Notificar cliente e ofertar nova via.
chargeback.created	Contestação aberta pelo cliente final junto ao banco emissor.	Suspender provisoriamente o serviço.
withdrawal.success	Saque da conta virtual creditado com sucesso no banco de destino.	Atualizar fluxo contábil interno.
withdrawal.failed	Saque recusado pela instituição de destino ou chave Pix inválida.	Estornar o saldo para a conta FastGivr.

---

🔒 Validação de Assinatura (X-FastGivr-Signature)

Para garantir que a notificação foi enviada pela FastGivr e não por um invasor simulando requisições, todas as requisições de Webhook contêm um cabeçalho HTTP de segurança:

X-FastGivr-Signature: <ASSINATURA_HMAC_SHA256>

Como Validar a Assinatura (Exemplo em Node.js/TypeScript)

A assinatura é calculada gerando um hash HMAC-SHA256 do corpo bruto da requisição (raw request body) utilizando o Segredo do Webhook (disponível na tela de configuração de webhook do portal) como chave secreta.

import crypto from 'crypto';
import { Request, Response } from 'express';

export function handleWebhook(req: Request, res: Response) {
  const secret = process.env.FASTGIVR_WEBHOOK_SECRET!; // Seu Segredo do Webhook
  const signature = req.headers['x-fastgivr-signature'] as string;
  
  // O corpo da requisição DEVE ser lido como string bruta (Raw Body)
  const rawBody = JSON.stringify(req.body);
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
    
  if (signature !== expectedSignature) {
    return res.status(401).send('Assinatura Inválida');
  }
  
  // Assinatura válida! Processar evento de forma assíncrona
  const event = req.body.event;
  console.log(`Evento recebido: ${event}`);
  
  return res.status(200).send('Recebido');
}

---

⏳ Política de Retentativas (Retry Policy)

Caso o seu servidor de webhook esteja temporariamente fora do ar ou retorne códigos HTTP diferentes de 2xx (como 500, 503, ou 408), a FastGivr adota uma política rígida de retentativas automáticas baseada em Intervalos Crescentes (Exponential Backoff):

• 1ª Retentativa: 5 minutos após a falha original.
• 2ª Retentativa: 15 minutos após a última falha.
• 3ª Retentativa: 30 minutos após a última falha.
• 4ª Retentativa: 1 hora após a última falha.
• 5ª Retentativa: 4 horas após a última falha.
• 6ª e Última Retentativa: 12 horas após a última falha.

Se após 6 tentativas o seu servidor continuar inacessível, a notificação é marcada como Falha Permanente no painel.

---

📄 Exemplo de Payload: charge.paid

Abaixo está o formato padrão enviado pela FastGivr em eventos de confirmação de pagamento:

{
  "event": "charge.paid",
  "created_at": "2026-05-18T15:10:00.000000Z",
  "data": {
    "id": "chg_9a8b7c6d5e",
    "amount": 150.00,
    "net_amount": 147.51,
    "fee": 2.49,
    "payment_method": "boleto",
    "status": "paid",
    "payer": {
      "name": "Cliente de Teste FastGivr",
      "document": "12345678909",
      "email": "cliente@teste.com"
    },
    "metadata": {
      "order_id": "ped_998822",
      "origin": "e-commerce"
    }
  }
}