Skip to main content

​
O que são Webhooks?

Webhooks são notificações HTTP enviadas automaticamente pela Flare Payments para a URL configurada no seu sistema quando um evento ocorre (ex: pagamento confirmado, saque concluído).

​
Eventos Suportados

EventoDescrição
charge.paidPagamento PIX confirmado
charge.expiredCobrança expirou sem pagamento
charge.failedErro no processamento da cobrança
transfer.completedSaque processado com sucesso
transfer.failedSaque falhou

​
Exemplos de Payload

{
  "event": "charge.paid",
  "data": {
    "id": "ch_flare_dc7dc11b7f984d2886d2b429",
    "object": "charge",
    "amount": 10.00,
    "amount_cents": 1000,
    "status": "paid",
    "description": "Pedido #1234",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com"
    },
    "paid_at": "2026-03-05T18:16:22.000Z",
    "created_at": "2026-03-05T18:14:48.552Z"
  }
}

{
  "event": "charge.expired",
  "data": {
    "id": "ch_flare_dc7dc11b7f984d2886d2b429",
    "object": "charge",
    "amount": 10.00,
    "status": "expired",
    "expires_at": "2026-03-05T19:14:48.549Z"
  }
}

{
  "event": "transfer.completed",
  "data": {
    "id": "wd_flare_a1b2c3d4e5f6a7b8c9d0e1f2",
    "object": "withdrawal",
    "amount": 100.00,
    "fee": 1.90,
    "net_amount": 98.10,
    "status": "paid"
  }
}

{
  "event": "transfer.failed",
  "data": {
    "id": "wd_flare_a1b2c3d4e5f6a7b8c9d0e1f2",
    "object": "withdrawal",
    "amount": 100.00,
    "status": "failed",
    "error": "Chave PIX inválida"
  }
}

​
Respondendo ao Webhook

Sua URL deve responder com HTTP 200 e o corpo { "received": true } em até 5 segundos: 
// Exemplo com Express.js
app.post('/webhooks/flare', (req, res) => {
  const { event, data } = req.body;

  // Processar o evento de forma assíncrona
  processarEvento(event, data).catch(console.error);

  // Responder imediatamente
  res.json({ received: true });
});
Processe a lógica de negócio de forma assíncrona. Se sua URL demorar mais de 5 segundos para responder, o webhook será considerado falho e retentativas serão feitas.

​
Boas Práticas

  • Seja idempotente: o mesmo evento pode ser entregue mais de uma vez. Use o id do objeto para evitar processamento duplicado
  • Responda rápido: retorne 200 imediatamente e processe em background
  • Valide o payload: verifique se o id existe no seu sistema antes de processar