> ## 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.

# Webhooks

> Receba notificações em tempo real sobre eventos de pagamento

## 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

<AccordionGroup>
  <Accordion title="charge.paid">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Accordion>

  <Accordion title="charge.expired">
    ```json theme={null}
    {
      "event": "charge.expired",
      "data": {
        "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
        "amount": 1000,
        "status": "expired",
        "expires_at": "2026-03-05T19:14:48.549Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="transfer.completed">
    ```json theme={null}
    {
      "event": "transfer.completed",
      "data": {
        "id": "wd_flare_a1b2c3d4e5f6a7b8c9d0e1f2",
        "object": "withdrawal",
        "amount": 100.00,
        "fee": 1.90,
        "net_amount": 98.10,
        "status": "paid"
      }
    }
    ```
  </Accordion>

  <Accordion title="transfer.failed">
    ```json theme={null}
    {
      "event": "transfer.failed",
      "data": {
        "id": "wd_flare_a1b2c3d4e5f6a7b8c9d0e1f2",
        "object": "withdrawal",
        "amount": 100.00,
        "status": "failed",
        "error": "Chave PIX inválida"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Respondendo ao Webhook

Sua URL deve responder com **HTTP 200** e o corpo `{ "received": true }` em até **5 segundos**:

```javascript theme={null}
// 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 });
});
```

<Warning>
  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.
</Warning>

***

## 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