Webhooks

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

Evento	Descrição
`charge.paid`	Pagamento PIX confirmado
`charge.expired`	Cobrança expirou sem pagamento
`charge.failed`	Erro no processamento da cobrança
`transfer.completed`	Saque processado com sucesso
`transfer.failed`	Saque falhou

Exemplos de Payload

charge.paid

{
  "event": "charge.paid",
  "data": {
    "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
    "amount": 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"
  }
}

charge.expired

{
  "event": "charge.expired",
  "data": {
    "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
    "amount": 1000,
    "status": "expired",
    "expires_at": "2026-03-05T19:14:48.549Z"
  }
}

transfer.completed

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

transfer.failed

{
  "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

Início

Conceitos

O que são Webhooks?

Eventos Suportados

Exemplos de Payload

Respondendo ao Webhook

Boas Práticas

​O que são Webhooks?

​Eventos Suportados

​Exemplos de Payload

​Respondendo ao Webhook

​Boas Práticas

O que são Webhooks?

Eventos Suportados

Exemplos de Payload

Respondendo ao Webhook

Boas Práticas