> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flarepayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão Geral dos Webhooks

> Como configurar e receber notificações em tempo real

## O que são Webhooks?

Webhooks permitem que a Flare Payments notifique seu sistema em tempo real quando um evento ocorre — por exemplo, quando um pagamento PIX é confirmado ou um saque é concluído.

Em vez de fazer polling constantemente, você configura uma URL e recebe a notificação automaticamente.

## Eventos Disponíveis

| Evento               | Quando ocorre                     |
| -------------------- | --------------------------------- |
| `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                      |

## Como Responder

Sua URL deve:

1. Retornar **HTTP 200** em até **5 segundos**
2. Retornar o corpo `{ "received": true }`
3. Processar a lógica de negócio de forma **assíncrona**

```javascript theme={null}
// Exemplo com Express.js
app.post('/webhooks/flare', express.json(), (req, res) => {
  const { event, data } = req.body;

  // [OK] Responda imediatamente
  res.json({ received: true });

  // [OK] Processe de forma assíncrona
  processarEvento(event, data).catch(console.error);
});
```

## Retentativas

Se sua URL retornar um status diferente de `200` ou demorar mais de 5 segundos, a Flare Payments fará retentativas automáticas com backoff exponencial.

<Warning>
  Implemente idempotência no seu handler. O mesmo evento pode ser entregue mais de uma vez. Use o `id` do objeto para evitar processamento duplicado.
</Warning>

## Verificar se é uma Cobrança Nova

```javascript theme={null}
const processados = new Set();

async function processarEvento(event, data) {
  // Evitar processamento duplicado
  if (processados.has(data.id)) return;
  processados.add(data.id);

  if (event === 'charge.paid') {
    await liberarPedido(data.id, data.amount);
  }
}
```

## Próximos Passos

<Card title="Referência de Eventos" icon="list" href="/api-reference/webhooks/events">
  Veja o payload completo de cada evento disponível
</Card>