Webhooks

Webhooks são notificações HTTP automáticas que o FastGivr envia para uma URL de sua escolha quando eventos financeiros ocorrem na sua conta — como um pagamento confirmado, um boleto liquidado ou um saque processado.

Acesso: Menu lateral → Webhooks (/webhooks)

---

O que são Webhooks?

Imagine webhooks como um sistema de "alertas automáticos". Em vez de seu sistema ficar consultando a API repetidamente para saber se um pagamento foi feito, o FastGivr avisa proativamente o seu sistema quando o evento acontece.

Fluxo Básico:

Cliente paga → FastGivr processa → FastGivr envia POST para sua URL → Seu sistema atualiza o pedido

---

Gerenciar Webhooks no Portal

Listar Webhooks Cadastrados

A tela principal exibe todos os endpoints cadastrados:

Coluna	Descrição
URL	Endereço do endpoint que recebe as notificações
Eventos	Tipos de eventos monitorados
Status	Ativo ou Inativo
Última entrega	Data e resultado do último envio
Ações	Editar, Testar, Desativar, Excluir

---

Cadastrar um Webhook

1. Na tela de Webhooks, clique em Novo Webhook.
2. Preencha os campos:

Campo	Obrigatório	Descrição
URL	✅ Sim	Endpoint HTTPS que receberá os eventos
Eventos	✅ Sim	Selecione os tipos de eventos a monitorar
Segredo (Secret)	Não	Token para validação de autenticidade
Status	✅ Sim	Ativo ou Inativo

3. Clique em Salvar.

A URL deve ser HTTPS e estar acessível publicamente. URLs de localhost não são aceitas em produção.

---

Eventos Disponíveis

Evento	Descrição
payment.confirmed	Pagamento confirmado (Pix, Boleto, Cartão)
payment.failed	Pagamento falhou ou expirou
payment.refunded	Estorno realizado
boleto.paid	Boleto liquidado pelo banco
boleto.expired	Boleto vencido sem pagamento
pix.received	Pix recebido na conta
pix.out.processed	Transferência Pix realizada com sucesso
withdraw.completed	Saque processado
chargeback.created	Chargeback recebido

---

Formato do Payload

O FastGivr envia um POST HTTP com Content-Type: application/json. Exemplo de payload para payment.confirmed:

{
  "event": "payment.confirmed",
  "account_id": "acc_xxxxxxxx",
  "data": {
    "id": "pay_xxxxxxxxxxxxxxxxxx",
    "amount": 15000,
    "amount_formatted": "R$ 150,00",
    "method": "pix",
    "status": "paid",
    "created_at": "2026-05-19T14:30:00Z",
    "paid_at": "2026-05-19T14:30:45Z",
    "customer": {
      "name": "João da Silva",
      "document": "123.456.789-00",
      "email": "joao@exemplo.com.br"
    },
    "charge": {
      "id": "cob_xxxxxxxxxxxxxxxxxx",
      "description": "Mensalidade Maio 2026"
    }
  }
}

Valores monetários são enviados em centavos (inteiro). 15000 = R$ 150,00.

---

Validação com Secret

Se você configurou um Secret, o FastGivr inclui um header de assinatura para que seu sistema valide a autenticidade do webhook:

X-FastGivr-Signature: sha256=a1b2c3d4e5f6...

Validação em PHP:

$payload = file_get_contents('php://input');
$secret = 'seu_secret_aqui';
$signature = hash_hmac('sha256', $payload, $secret);
$receivedSignature = str_replace('sha256=', '', $_SERVER['HTTP_X_FASTGIVR_SIGNATURE']);

if (!hash_equals($signature, $receivedSignature)) {
    http_response_code(401);
    exit('Assinatura inválida');
}

---

Retentativas (Retry)

Se sua URL retornar um status HTTP diferente de 2xx, o FastGivr realiza retentativas automáticas:

Tentativa	Intervalo
1ª retentativa	5 minutos
2ª retentativa	15 minutos
3ª retentativa	1 hora
4ª retentativa	6 horas

Após 4 falhas, o webhook é marcado como com erro e você recebe um alerta no portal.

---

Testar um Webhook

Para verificar se sua URL está respondendo corretamente:

1. Na listagem, clique em Testar na linha do webhook.
2. O sistema envia um payload de teste para a URL configurada.
3. O resultado (código HTTP e corpo da resposta) é exibido na tela.

---

Logs de Entrega

Cada webhook possui um histórico de entregas com:

• Data e hora do envio
• Evento disparado
• Status HTTP da resposta
• Corpo da resposta recebida
• Tempo de resposta (ms)

Use os logs para diagnosticar falhas de integração.

---

Boas Práticas

• Responda rapidamente: Seu endpoint deve responder em menos de 5 segundos para não ser marcado como falha.
• Processe assincronamente: Ao receber o webhook, salve em fila e processe em background — não faça operações pesadas na resposta.
• Valide o Secret: Sempre valide a assinatura para evitar payloads falsificados.
• Seja idempotente: O mesmo evento pode ser entregue mais de uma vez. Seu sistema deve tratar duplicatas.
• Use HTTPS: URLs HTTP não são suportadas em produção por questões de segurança.