Copy page

Plataforma

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. Para pasos de verificación HMAC, consulta Verificación de firma de webhook.

Formato de sobre

Cada webhook entregado usa la misma estructura de nivel superior:

Code
{
  "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 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

---

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

Code
{
  "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
• 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

Code
{
  "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

---

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).

---

Probar webhooks

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

Code
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.

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 — registro, secretos, mejores prácticas
• Verificación de firma de webhook — verificación HMAC-SHA256
• Solicitudes de pago — ciclo de vida completo de estados
• Reembolsos — API de reembolsos y estados