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

> Payloads e eventos enviados para sua aplicação

# Webhooks

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

A Velfy Payments notifica sua aplicação em tempo real através de requisições `POST` para a URL configurada, sempre que o status de uma transação muda.

## 🔧 Configurando a URL de Destino

Informe a URL para onde deseja receber as notificações no campo `postbackUrl`, ao criar a transação:

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

Todos os eventos relacionados a essa transação serão enviados para essa URL.

## 📡 Formato da Notificação

```text theme={null}
POST {sua postbackUrl}
Content-Type: application/json
```

```json theme={null}
{
  "id": 4587123,
  "type": "transaction",
  "url": "https://sualoja.com/webhooks/velfy",
  "data": {
    "id": 918234,
    "status": "paid",
    "amount": 10000,
    "paidAmount": 10000,
    "paidAt": "2026-07-28T12:05:00.000Z",
    "paymentMethod": "pix",
    "externalRef": "pedido-123",
    "secureId": "9c1a9b2e-7c3d-4e11-9a2f-3a1c5f0e9d21",
    "fee": {
      "netAmount": 9700,
      "fixedAmount": 300,
      "estimatedFee": 300
    },
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix0136...6304ABCD",
      "end2end": "E00000000202607281200abc123def456"
    },
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "document": { "type": "cpf", "number": "12345678900" }
    },
    "createdAt": "2026-07-28T12:00:00.000Z"
  }
}
```

<Note>
  Quando a transação for de **boleto**, o objeto `data.boleto` (`url`, `barcode`, `digitableLine`) é enviado no lugar de `data.pix`.
</Note>

## 🔹 Eventos Disponíveis

O campo `data.status` reflete o mesmo status retornado pelos endpoints de criação e consulta de transação:

| Evento (`data.status`) | Quando é enviado                      |
| ---------------------- | ------------------------------------- |
| `pending`              | Cobrança criada, aguardando pagamento |
| `processing`           | Pagamento em processamento            |
| `paid`                 | Pagamento confirmado (PIX/boleto)     |
| `approved`             | Pagamento aprovado (cartão)           |
| `refused`              | Pagamento recusado                    |
| `refunded`             | Pagamento estornado                   |
| `chargedback`          | Chargeback recebido                   |
| `in_protest`           | Chargeback em contestação             |

## 🔄 Implementação Recomendada

```js theme={null}
app.post('/webhooks/velfy', async (req, res) => {
  const { data } = req.body

  // Responda rapidamente e processe de forma assíncrona
  res.status(200).send('OK')

  switch (data.status) {
    case 'paid':
    case 'approved':
      await releaseProduct(data.externalRef)
      break
    case 'refunded':
      await cancelDelivery(data.externalRef)
      break
    default:
      await logTransactionUpdate(data)
  }
})
```

## 🛡️ Boas Práticas

<AccordionGroup>
  <Accordion title="🔄 Idempotência" icon="arrows-rotate">
    * Use o campo `data.id` (id da transação) para não processar o mesmo evento duas vezes
    * Armazene o último status processado antes de agir sobre um novo evento
  </Accordion>

  <Accordion title="⚡ Performance" icon="bolt">
    * Responda com HTTP `200` o mais rápido possível
    * Processe a lógica de negócio de forma assíncrona (fila, job, etc)
  </Accordion>

  <Accordion title="📊 Monitoramento" icon="chart-line">
    * Monitore falhas de entrega no seu endpoint
    * Use `GET /api/v1/transactions/{id}` para conciliar dados quando necessário
  </Accordion>
</AccordionGroup>

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="💰 PIX" color="#631286" icon="qrcode" href="/api-reference/payments/pix">
    Gere cobranças PIX com QR Code
  </Card>

  <Card title="💳 Cartão de Crédito" color="#631286" icon="credit-card" href="/api-reference/payments/credit-card">
    Tokenize e cobre no cartão
  </Card>
</CardGroup>