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

# Visão Geral

> Receba notificações automáticas sobre o status das suas transações PIX

## O que são Webhooks?

Os **Webhooks PIX** permitem que você receba notificações em tempo real quando o status de uma transação PIX muda. Em vez de fazer polling constantemente na API, seu sistema é notificado automaticamente quando eventos importantes ocorrem.

<Info>
  Webhooks são a forma recomendada de acompanhar o status das transações. Eles reduzem a latência e o consumo de recursos comparado ao polling.
</Info>

### Características

* Notificações em tempo real
* Suporte a 4 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out)
* Retentativas automáticas em caso de falha
* Autenticação via Basic Auth
* Payload padronizado em JSON

***

## Eventos Disponíveis

<CardGroup cols={2}>
  <Card title="CashIn" icon="arrow-down" href="/api-reference/guides/webhooks/cash-in">
    Recebimento PIX confirmado (CREDIT)
  </Card>

  <Card title="CashOut" icon="arrow-up" href="/api-reference/guides/webhooks/cash-out">
    Envio PIX confirmado (DEBIT)
  </Card>

  <Card title="CashInReversal" icon="rotate-left" href="/api-reference/guides/webhooks/cash-in-reversal">
    Estorno de recebimento (DEBIT)
  </Card>

  <Card title="CashOutReversal" icon="rotate" href="/api-reference/guides/webhooks/cash-out-reversal">
    Devolução de envio recebida (CREDIT)
  </Card>
</CardGroup>

| Evento     | `event`           | `movementType` | Descrição                                            |
| ---------- | ----------------- | -------------- | ---------------------------------------------------- |
| PIX In     | `CashIn`          | `CREDIT`       | Recebimento PIX confirmado                           |
| PIX Out    | `CashOut`         | `DEBIT`        | Envio PIX confirmado                                 |
| Refund In  | `CashInReversal`  | `DEBIT`        | Estorno de recebimento (devolução iniciada por você) |
| Refund Out | `CashOutReversal` | `CREDIT`       | Devolução de envio (devolução recebida)              |

***

## Configuração do Endpoint

Para receber webhooks, você precisa:

<Steps>
  <Step title="Configurar URL de Webhook">
    Use a [API de Configuração de Webhooks](/api-reference/guides/webhooks/setup) para definir a URL do seu endpoint programaticamente.
  </Step>

  <Step title="Implementar Endpoint">
    Crie um endpoint HTTPS que aceite requisições POST e retorne HTTP 200 rapidamente.
  </Step>

  <Step title="Validar Autenticação">
    Configure a validação do header de autenticação Basic Auth.
  </Step>
</Steps>

### Requisitos Técnicos

| Requisito    | Descrição                    |
| ------------ | ---------------------------- |
| Protocolo    | HTTPS obrigatório            |
| Método       | POST                         |
| Timeout      | Responder em até 10 segundos |
| Response     | HTTP 200 OK                  |
| Content-Type | application/json             |

<Warning>
  Se seu endpoint não responder com HTTP 200 dentro de 10 segundos, o webhook será considerado como falha e será retentado.
</Warning>

***

## Autenticação Basic Auth

Os webhooks são enviados com autenticação **Basic Auth** no header:

```
Authorization: Basic base64(username:password)
```

```javascript theme={null}
// Node.js/Express - Validação
app.post('/webhooks/pix', (req, res) => {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Basic ')) {
    return res.status(401).send('Unauthorized');
  }

  const base64Credentials = authHeader.split(' ')[1];
  const credentials = Buffer.from(base64Credentials, 'base64').toString('ascii');
  const [username, password] = credentials.split(':');

  if (username !== process.env.WEBHOOK_USER || password !== process.env.WEBHOOK_PASS) {
    return res.status(401).send('Unauthorized');
  }

  // Processar webhook...
  res.status(200).json({ acknowledged: true });
});
```

***

## Estrutura Base do Payload

Todos os webhooks compartilham uma estrutura base comum:

```json theme={null}
{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "12345",
  "externalId": "PIX-5482123298-EJUYFSMU1UU",
  "endToEndId": "E00416968202512111942rjzxxzSSTD9",
  "pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
  "feeAmount": 0.01,
  "originalAmount": 0.5,
  "finalAmount": 0.49,
  "processingDate": "2025-12-11T19:42:04.080Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {}
}
```

<AccordionGroup>
  <Accordion title="Campos Obrigatórios">
    <ParamField path="event" type="string" required>
      Tipo do evento.

      **Valores possíveis:** `CashIn`, `CashOut`, `CashInReversal`, `CashOutReversal`
    </ParamField>

    <ParamField path="status" type="string" required>
      Status da transação.

      **Valores possíveis:** `PENDING`, `CONFIRMED`, `ERROR`
    </ParamField>

    <ParamField path="transactionType" type="string" required>
      Tipo de transação. Sempre `PIX` para webhooks PIX.
    </ParamField>

    <ParamField path="movementType" type="string" required>
      Tipo de movimento na conta.

      * `CREDIT`: Entrada de recursos (recebimento ou devolução recebida)
      * `DEBIT`: Saída de recursos (envio ou estorno)
    </ParamField>

    <ParamField path="transactionId" type="string" required>
      ID numérico da transação na Fire Banking (retornado como string).

      **Exemplo:** `"12345"`
    </ParamField>

    <ParamField path="endToEndId" type="string" required>
      ID End-to-End gerado pelo Banco Central para rastreamento.

      **Exemplo:** `"E00416968202512111942rjzxxzSSTD9"`
    </ParamField>

    <ParamField path="processingDate" type="string" required>
      Data e hora do processamento (ISO 8601 UTC).

      **Exemplo:** `"2025-12-11T19:42:04.080Z"`
    </ParamField>
  </Accordion>

  <Accordion title="Campos de Valores">
    <ParamField path="feeAmount" type="number" required>
      Taxa cobrada pela transação em reais (BRL).

      **Exemplo:** `0.01`
    </ParamField>

    <ParamField path="originalAmount" type="number" required>
      Valor original da transação em reais (BRL).

      **Exemplo:** `0.50`
    </ParamField>

    <ParamField path="finalAmount" type="number" required>
      Valor final após aplicação de taxas.

      * Para `CREDIT`: `originalAmount - feeAmount`
      * Para `DEBIT`: `originalAmount + feeAmount`
    </ParamField>
  </Accordion>

  <Accordion title="Campos Opcionais">
    <ParamField path="externalId" type="string">
      ID externo fornecido na criação da transação.

      **Exemplo:** `"PIX-5482123298-EJUYFSMU1UU"`
    </ParamField>

    <ParamField path="pixKey" type="string">
      Chave PIX utilizada na transação (CPF, CNPJ, email, telefone ou chave aleatória).
    </ParamField>

    <ParamField path="errorCode" type="string">
      Código de erro quando `status` é `ERROR`. Nulo se sucesso.
    </ParamField>

    <ParamField path="errorMessage" type="string">
      Mensagem de erro descritiva. Nulo se sucesso.
    </ParamField>

    <ParamField path="metadata" type="object">
      Metadados adicionais específicos do evento.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Configurar Webhooks" icon="gear" href="/api-reference/guides/webhooks/setup">
    Configure URLs de webhook via API
  </Card>

  <Card title="CashIn" icon="arrow-down" href="/api-reference/guides/webhooks/cash-in">
    Detalhes do evento de recebimento
  </Card>

  <Card title="CashOut" icon="arrow-up" href="/api-reference/guides/webhooks/cash-out">
    Detalhes do evento de envio
  </Card>

  <Card title="CashInReversal" icon="rotate-left" href="/api-reference/guides/webhooks/cash-in-reversal">
    Detalhes do evento de estorno
  </Card>

  <Card title="CashOutReversal" icon="rotate" href="/api-reference/guides/webhooks/cash-out-reversal">
    Detalhes do evento de devolução
  </Card>
</CardGroup>