# Eventos de webhook

Esta página cataloga tipos de eventos de webhook, formas de payload y comportamiento de entrega. Para registro, encabezados y seguridad, empieza con [Webhooks](/es/docs/developers/webhooks). Para pasos de verificación HMAC, consulta [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification).

## Formato de sobre

Cada webhook entregado usa la misma estructura de nivel superior:

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

Fluxis firma el **cuerpo JSON parseado completo** (el objeto que contiene `data`), no solo el objeto interno `data` ni bytes crudos de la solicitud. Los campos opcionales omitidos del payload (Go `omitempty`) afectan la firma — verifica siempre contra el JSON que realmente recibiste.

### Encabezados de entrega

| Encabezado | Descripción |
| ------ | ----------- |
| `X-Request-Signature` | HMAC-SHA256 codificado en hexadecimal |
| `X-Request-Timestamp` | Marca de tiempo Unix (segundos) |
| `Content-Type` | `application/json` |

Rechaza solicitudes con más de **300 segundos**. Consulta la [guía de verificación de firmas](/es/docs/developers/webhook-signature-verification) para el algoritmo completo.

## Tipos de evento

Los webhooks se registran **por cuenta** vía `POST /v1/account/{accountID}/webhook`. Cada registro se suscribe a un `event_type`:

| `event_type` | `notification_type` en el payload | Estado de entrega |
| ------------ | ------------------------------ | --------------- |
| `payment_request` | `payment_request_status_update` | **Activo** |
| `refund` | `refund_status_update` | **Activo** (al crear reembolso) |
| `incoming_transfer` | — | **Reservado / futuro** |

::::info
`incoming_transfer` puede registrarse en la API hoy, pero **ninguna ruta de código de producción despacha este evento aún**. No construyas integraciones que dependan de él hasta que Fluxis anuncie disponibilidad.
::::

---

## Eventos `payment_request`

Suscríbete con `"event_type": "payment_request"`.

### Cuándo se disparan

Fluxis envía un webhook cuando el estado de la solicitud de pago cambia a:

| Estado | Disparador |
| ------ | ------- |
| `processing` | Depósito on-chain detectado; verificación de finalidad en cola |
| `completed` | Pago completo recibido |
| `underpaid` | Pago recibido por debajo del monto solicitado |
| `overpaid` | Pago recibido por encima del monto solicitado |

Estados como `pending`, `created`, `expired`, `failed` y `confirmed` **no** disparan webhooks `payment_request` hoy.

### Campos del 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 | Descripción |
| ----- | ----------- |
| `notification_type` | Siempre `payment_request_status_update` |
| `payment_request_id` | UUID de solicitud de pago de Fluxis |
| `payment_request_type` | `fixed`, `dynamic`, `pre_loaded` o `open` |
| `external_reference_id` | Tu referencia de pedido (opcional; omitido si no está definido) |
| `status` | Estado actual de la solicitud de pago |
| `point_of_sale_id` | POS que creó la solicitud de pago |
| `account_id` | Cuenta propietaria (opcional; omitido si no está definido) |

### Orientación de integración

- Trata `processing` como "pago detectado" — espera un estado terminal antes de entregar bienes
- Maneja `underpaid` y `overpaid` según la configuración de tu POS; puede que necesites emitir un [reembolso](/es/docs/developers/refunds)
- Usa `external_reference_id` para mapear eventos a tu sistema de pedidos

---

## Eventos `refund`

Suscríbete con `"event_type": "refund"`.

### Cuándo se disparan

Se envía un webhook cuando se **crea** un reembolso vía `POST /v1/refunds/payment-request/{paymentRequestID}`. Actualizaciones de estado adicionales (`completed`, `failed`) se dispararán cuando se implemente la ejecución on-chain de reembolsos.

### Campos del 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 | Descripción |
| ----- | ----------- |
| `notification_type` | Siempre `refund_status_update` |
| `refund_request_id` | UUID de reembolso de Fluxis |
| `payment_request_id` | Solicitud de pago original |
| `status` | `processing`, `completed` o `failed` |
| `amount` | Monto del reembolso como cadena decimal |

::::warning
La ejecución on-chain de reembolsos aún no está implementada. Espera `status: "processing"` al crear hasta que las transferencias salientes estén activas. Consulta [Reembolsos](/es/docs/developers/refunds).
::::

---

## `incoming_transfer` (reservado)

Suscríbete con `"event_type": "incoming_transfer"`.

Este tipo de evento está definido en la API y puede registrarse, pero **Fluxis no despacha webhooks `incoming_transfer` en código de producción hoy**. Está reservado para una función futura (transferencias entrantes directas no vinculadas a un flujo de solicitud de pago).

::::note
Si registras un webhook `incoming_transfer`, permanecerá inactivo hasta que Fluxis habilite la entrega. Monitorea las notas de versión antes de construir contra este evento.
::::

---

## Probar webhooks

Envía un payload de prueba firmado a tu endpoint:

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

La prueba usa un cuerpo de muestra `payment_request_status_update`. Verifícalo con el mismo algoritmo que los eventos de producción — consulta [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification).

## Matriz estado → webhook

| Estado de solicitud de pago | ¿Webhook enviado? |
| ---------------------- | ------------- |
| `pending` | No |
| `created` | No |
| `processing` | Sí |
| `completed` | Sí |
| `underpaid` | Sí |
| `overpaid` | Sí |
| `confirmed` | No |
| `expired` | No |
| `failed` | No |

## Documentación relacionada

- [Webhooks](/es/docs/developers/webhooks) — registro, secretos, mejores prácticas
- [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification) — verificación HMAC-SHA256
- [Solicitudes de pago](/es/docs/key-concepts/payment-request) — ciclo de vida completo de estados
- [Reembolsos](/es/docs/developers/refunds) — API de reembolsos y estados