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

# Webhooks

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

# Webhooks

> Receba notificações automáticas sempre que o status de uma cobrança mudar

Em vez de ficar consultando o status de uma transação repetidamente (polling), configure um webhook e a Velfy avisa sua aplicação em tempo real, via `POST`, sempre que houver uma mudança.

## Como configurar

Basta informar a URL de destino no campo `postbackUrl`, ao criar a cobrança:

```json theme={null}
{
  "paymentMethod": "pix",
  "postbackUrl": "https://sualoja.com/webhooks/velfy"
}
```

Todo evento relacionado àquela transação específica será enviado para essa URL.

## O que esperar na notificação

A Velfy envia um payload JSON contendo o tipo do evento e os dados atualizados da transação — incluindo o status atual, valores pagos/estornados e os dados específicos do método de pagamento usado (QR Code do PIX, linha digitável do boleto, etc).

## Eventos principais

| Evento             | Quando acontece                                 |
| ------------------ | ----------------------------------------------- |
| Cobrança gerada    | PIX ou boleto criados, aguardando pagamento     |
| Pagamento aprovado | Pagamento confirmado — libere o produto/serviço |
| Pagamento recusado | Cartão recusado pela operadora                  |
| Estorno            | Valor devolvido ao pagador                      |
| Chargeback         | Contestação recebida na operadora de cartão     |

## Como processar corretamente

<Steps>
  <Step title="Responda rápido">
    Retorne `200 OK` assim que receber a notificação, antes de processar qualquer lógica de negócio.
  </Step>

  <Step title="Processe de forma assíncrona">
    Depois de responder, trate o evento em background (fila, job) — evita timeouts e reentregas desnecessárias.
  </Step>

  <Step title="Seja idempotente">
    O mesmo evento pode ser reentregue mais de uma vez. Use o id da transação para não processar o mesmo pagamento duas vezes.
  </Step>
</Steps>

## Boas práticas

<AccordionGroup>
  <Accordion title="Confiabilidade" icon="arrows-rotate">
    * Armazene o último status processado antes de agir sobre um novo evento
    * Monitore falhas de entrega no seu endpoint
  </Accordion>

  <Accordion title="Reconciliação" icon="magnifying-glass">
    * Use o endpoint de consulta de transação para conferir o estado real sempre que houver dúvida sobre um evento perdido
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência técnica" icon="book" href="/api-reference/payments/webhooks">
    Veja o payload completo e todos os status possíveis
  </Card>

  <Card title="PIX Out" icon="money-bill-transfer" href="/guides/pix-out">
    Envie transferências PIX pela sua conta Velfy
  </Card>
</CardGroup>