# Eventos de webhook

Esta página cataloga tipos de eventos de webhook, formatos de payload e comportamento de entrega. Para registro, cabeçalhos e segurança, comece em [Webhooks](/pt/docs/developers/webhooks). Para passos de verificação HMAC, consulte [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification).

## Formato de envelope

Cada webhook entregue usa a mesma estrutura de nível superior:

```json
{
  "data": {
    "notification_type": "...",
    ...
  }
}
```

A Fluxis assina o **corpo JSON parseado completo** (o objeto que contém `data`), não apenas o objeto interno `data` nem bytes brutos da requisição. Campos opcionais omitidos no payload (Go `omitempty`) afetam a assinatura — sempre verifique contra o JSON que você realmente recebeu.

### Cabeçalhos de entrega

| Cabeçalho | Descrição |
| ------ | ----------- |
| `X-Request-Signature` | HMAC-SHA256 codificado em hexadecimal |
| `X-Request-Timestamp` | Timestamp Unix (segundos) |
| `Content-Type` | `application/json` |

Rejeite requisições com mais de **300 segundos**. Consulte o [guia de verificação de assinatura](/pt/docs/developers/webhook-signature-verification) para o algoritmo completo.

## Tipos de evento

Webhooks são registrados **por conta** via `POST /v1/account/{accountID}/webhook`. Cada registro assina um `event_type`:

| `event_type` | `notification_type` no payload | Status de entrega |
| ------------ | ------------------------------ | --------------- |
| `payment_request` | `payment_request_status_update` | **Ativo** |
| `refund` | `refund_status_update` | **Ativo** (na criação do reembolso) |
| `incoming_transfer` | — | **Reservado / futuro** |

::::info
`incoming_transfer` pode ser registrado na API hoje, mas **nenhum caminho de código em produção despacha este evento ainda**. Não construa integrações que dependam dele até a Fluxis anunciar disponibilidade.
::::

---

## Eventos `payment_request`

Assine com `"event_type": "payment_request"`.

### Quando disparam

A Fluxis envia um webhook quando o status da solicitação de pagamento muda para:

| Status | Gatilho |
| ------ | ------- |
| `processing` | Depósito on-chain detectado; verificação de finalidade enfileirada |
| `completed` | Pagamento integral recebido |
| `underpaid` | Pagamento recebido abaixo do valor solicitado |
| `overpaid` | Pagamento recebido acima do valor solicitado |

Status como `pending`, `created`, `expired`, `failed` e `confirmed` **não** disparam webhooks `payment_request` hoje.

### Campos do payload

```json
{
  "data": {
    "notification_type": "payment_request_status_update",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "payment_request_type": "fixed",
    "external_reference_id": "order-123",
    "status": "completed",
    "point_of_sale_id": "3cc1f7ca-c017-4e7e-b00d-aca0da6e464e",
    "account_id": "c87464d1-c54a-48c3-80c9-bee4fddf593d"
  }
}
```

| Campo | Descrição |
| ----- | ----------- |
| `notification_type` | Sempre `payment_request_status_update` |
| `payment_request_id` | UUID da solicitação de pagamento Fluxis |
| `payment_request_type` | `fixed`, `dynamic`, `pre_loaded` ou `open` |
| `external_reference_id` | Sua referência de pedido (opcional; omitido se não definido) |
| `status` | Status atual da solicitação de pagamento |
| `point_of_sale_id` | POS que criou a solicitação de pagamento |
| `account_id` | Conta proprietária (opcional; omitido se não definido) |

### Orientação de integração

- Trate `processing` como "pagamento detectado" — aguarde um status terminal antes de entregar mercadorias
- Trate `underpaid` e `overpaid` conforme a configuração do seu POS; pode ser necessário emitir um [reembolso](/pt/docs/developers/refunds)
- Use `external_reference_id` para mapear eventos ao seu sistema de pedidos

---

## Eventos `refund`

Assine com `"event_type": "refund"`.

### Quando disparam

Um webhook é enviado quando um reembolso é **criado** via `POST /v1/refunds/payment-request/{paymentRequestID}`. Atualizações de status adicionais (`completed`, `failed`) dispararão quando a execução on-chain de reembolsos for implementada.

### Campos do payload

```json
{
  "data": {
    "notification_type": "refund_status_update",
    "refund_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "status": "processing",
    "amount": "50.00"
  }
}
```

| Campo | Descrição |
| ----- | ----------- |
| `notification_type` | Sempre `refund_status_update` |
| `refund_request_id` | UUID de reembolso Fluxis |
| `payment_request_id` | Solicitação de pagamento original |
| `status` | `processing`, `completed` ou `failed` |
| `amount` | Valor do reembolso como string decimal |

::::warning
A execução on-chain de reembolsos ainda não está implementada. Espere `status: "processing"` na criação até que transferências de saída estejam ativas. Consulte [Reembolsos](/pt/docs/developers/refunds).
::::

---

## `incoming_transfer` (reservado)

Assine com `"event_type": "incoming_transfer"`.

Este tipo de evento está definido na API e pode ser registrado, mas **a Fluxis não despacha webhooks `incoming_transfer` em código de produção hoje**. Está reservado para um recurso futuro (transferências recebidas diretas não vinculadas a um fluxo de solicitação de pagamento).

::::note
Se você registrar um webhook `incoming_transfer`, ele permanecerá inativo até a Fluxis habilitar a entrega. Acompanhe as notas de versão antes de construir contra este evento.
::::

---

## Testar webhooks

Envie um payload de teste assinado ao seu endpoint:

```
POST /v1/account/{accountID}/webhook/{webhookID}/test
```

O teste usa um corpo de amostra `payment_request_status_update`. Verifique com o mesmo algoritmo dos eventos de produção — consulte [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification).

## Matriz status → webhook

| Status da solicitação de pagamento | Webhook enviado? |
| ---------------------- | ------------- |
| `pending` | Não |
| `created` | Não |
| `processing` | Sim |
| `completed` | Sim |
| `underpaid` | Sim |
| `overpaid` | Sim |
| `confirmed` | Não |
| `expired` | Não |
| `failed` | Não |

## Documentação relacionada

- [Webhooks](/pt/docs/developers/webhooks) — registro, segredos, boas práticas
- [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification) — verificação HMAC-SHA256
- [Solicitações de pagamento](/pt/docs/key-concepts/payment-request) — ciclo de vida completo de status
- [Reembolsos](/pt/docs/developers/refunds) — API de reembolsos e status