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

# Webhooks

> Sistema de notificações automáticas em tempo real

Os webhooks da API Avantti Finance permitem que sua aplicação receba notificações automáticas quando eventos importantes acontecem em sua conta, como pagamentos recebidos, transferências concluídas e mudanças de status.

## Como funcionam

Os webhooks são enviados automaticamente via **POST** para as URLs que você configurar sempre que eventos relevantes ocorrem em sua conta. Isso elimina a necessidade de fazer polling constante na API.

### Vantagens dos webhooks

<CardGroup cols={2}>
  <Card title="Tempo real" color="#ff7e00" icon="bolt">
    Receba notificações instantâneas sobre mudanças importantes
  </Card>

  <Card title="Confiabilidade" color="#ff7e00" icon="shield-check">
    Sistema de retry automático para garantir entrega
  </Card>

  <Card title="Flexibilidade" color="#ff7e00" icon="sliders">
    Configure diferentes endpoints para diferentes tipos de evento
  </Card>
</CardGroup>

## Eventos disponíveis

### Eventos de transação (PIX IN)

| Evento                   | Descrição             | Quando é enviado             |
| ------------------------ | --------------------- | ---------------------------- |
| `transaction_created`    | Transação criada      | QR Code gerado com sucesso   |
| `transaction_paid`       | Transação paga        | PIX recebido e confirmado    |
| `transaction_refunded`   | Transação estornada   | Estorno processado           |
| `transaction_infraction` | Infração na transação | Problemas detectados pelo BC |

### Eventos de transferência (PIX OUT)

| Evento               | Descrição                | Quando é enviado        |
| -------------------- | ------------------------ | ----------------------- |
| `transfer_created`   | Transferência criada     | Transferência iniciada  |
| `transfer_completed` | Transferência concluída  | PIX enviado com sucesso |
| `transfer_canceled`  | Transferência cancelada  | Transferência cancelada |
| `transfer_updated`   | Transferência atualizada | Status alterado         |

## Estrutura dos webhooks

<CodeGroup>
  ```json PIX IN theme={null}
  {
    "id": "wh_64f8a2b1c3d4e5f6g7h8i9j0",
    "type": "transaction",
    "event": "transaction_paid",
    "scope": "user",
    "transaction": {
      "id": "clm8x9y0z1234567890abcdef",
      "amount": 29990,
      "status": "paid",
      "pix": {
        "endToEndId": "E12345678202412011030567890AB123C",
        "payerInfo": {
          "name": "Maria Silva Santos",
          "document": "12345678901"
        }
      }
    }
  }
  ```

  ```json PIX OUT theme={null}
  {
    "id": "wh_75g9b3c2d4e5f6g7h8i9j0k1",
    "type": "transfer",
    "event": "transfer_completed",
    "scope": "user",
    "transfer": {
      "id": "cln1a2b3c4567890defghijk",
      "amount": 150000,
      "status": "completed",
      "pix": {
        "endToEndId": "E87654321202412011145543210ZY987X",
        "creditorAccount": {
          "bank": "341",
          "branch": "1234",
          "account": "567890"
        }
      }
    }
  }
  ```
</CodeGroup>

## Sistema de retry

Se seu endpoint não responder com status 200, implementamos um sistema de retry automático:

* **1ª tentativa**: Imediatamente
* **2ª tentativa**: Após 1 minuto
* **3ª tentativa**: Após 5 minutos
* **4ª tentativa**: Após 15 minutos
* **5ª tentativa**: Após 1 hora

<Tip>
  Após 5 tentativas sem sucesso, o webhook é marcado como falhado e você pode visualizar no dashboard.
</Tip>

## Monitoramento

### Dashboard de webhooks

No seu dashboard você pode:

* Ver histórico de webhooks enviados
* Verificar status de entrega
* Reenviar webhooks falhados
* Visualizar logs detalhados

### Logs úteis

```javascript theme={null}
// Log estruturado para debugging
console.log({
  timestamp: new Date().toISOString(),
  webhookId: event.id,
  eventType: event.event,
  processed: true,
  processingTime: Date.now() - startTime
})
```

## Troubleshooting

### Problemas comuns

<AccordionGroup>
  <Accordion title="Webhook não está sendo recebido">
    * Verifique se a URL está acessível publicamente
    * Confirme se está respondendo com status 200
    * Teste com ferramentas como ngrok para desenvolvimento local
    * Verifique se não há firewall bloqueando
  </Accordion>

  <Accordion title="Erro de verificação de assinatura">
    * Confirme se está usando o `signatureSecret` correto
    * Verifique se o payload não foi modificado
    * Use o body raw da requisição para verificação
    * Certifique-se de usar UTF-8 encoding
  </Accordion>

  <Accordion title="Webhooks duplicados">
    * Implemente processamento idempotente
    * Use o `id` do evento para deduplicação
    * Armazene IDs processados em cache/banco
    * Sempre responda 200 para eventos já processados
  </Accordion>
</AccordionGroup>

***

## Suporte

**Horário**: Segunda a Sexta, 08h às 18h (BRT)

**Bug Bounty**: Temos programa de recompensas para vulnerabilidades

<Info>
  **Dica**: Use ferramentas como [webhook.site](https://webhook.site) para testar e debuggar seus webhooks durante o desenvolvimento.
</Info>