Referencia de Eventos

Referencia de Eventos

Venflow emite eventos que cubren el ciclo de vida de clientes, suscripciones, facturas y pagos, además de eventos a nivel de organización (como el vencimiento de las credenciales del gateway).

Tipos de Eventos

Eventos a nivel de cliente

Eventos a nivel de organización

A diferencia de los anteriores, estos eventos no incluyen el objeto client porque corresponden a la organización, no a un cliente puntual.

Campo común: livemode

Además de los campos propios de cada tipo, todo payload incluye livemode:

Si tu handler escribe en tu contabilidad, haz que ignore (o registre aparte) todo lo que llegue con livemode: false.

USER_CREATE_EVENT

Se envía cuando se crea un nuevo cliente durante el flujo de checkout. Solo se dispara para clientes nuevos, no cuando se reutiliza un cliente existente.

{
  "eventType": "USER_CREATE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  }
}

SUBSCRIPTION_CREATE_EVENT

Se envía cuando se crea una suscripción durante el flujo de checkout, después de la activación del plan.

{
  "eventType": "SUBSCRIPTION_CREATE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "active",
    "externalId": "EXT123456"
  }
}

Campos de subscription

SUBSCRIPTION_UPDATED_EVENT

Se envía cuando una suscripción cambia de estado y ese cambio no está cubierto por SUBSCRIPTION_CREATE_EVENT ni por SUBSCRIPTION_CANCELLED_EVENT. El caso habitual es la morosidad: pasa de active a past_due cuando un cobro falla, y vuelve a active cuando se recupera.

Es el único evento que incluye previousStatus, así que puedes saber de dónde venía la suscripción sin guardar el estado anterior por tu cuenta.

{
  "eventType": "SUBSCRIPTION_UPDATED_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "past_due",
    "previousStatus": "active",
    "externalId": "EXT123456"
  }
}

Campos de subscription

SUBSCRIPTION_CANCELLED_EVENT

Se envía cuando una suscripción es cancelada. Incluye el motivo de cancelación.

{
  "eventType": "SUBSCRIPTION_CANCELLED_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "cancelled",
    "externalId": "EXT123456",
    "cancellationReason": {
      "type": "payment_failure",
      "message": "Retry window exceeded"
    }
  }
}

Campos de cancellationReason

INVOICE_CREATE_EVENT

Se envía cuando se genera una factura durante el proceso de pago de suscripción. La factura se crea con estado open.

{
  "eventType": "INVOICE_CREATE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "active",
    "externalId": "EXT123456"
  },
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "open",
    "total": "3907.85",
    "amountDue": "3907.85",
    "totalUsd": "5.79",
    "exchangeRate": "674.9305"
  }
}

Campos de invoice

Los dos viajan juntos: o totalUsd y exchangeRate llegan los dos con valor, o llegan los dos en null. Nunca vas a recibir una tasa sin el monto en dólares al que aplica, ni al revés.

INVOICE_UPDATE_EVENT

Se envía cuando cambia el estado de una factura. Los estados que lo disparan son:

• paid: la factura fue pagada exitosamente (amountDue pasa a "0")
• uncollectible: el cobro no pudo completarse después de agotar los reintentos
• cancelled: la factura fue anulada manualmente, desde el dashboard o por API. En la API de facturas, este estado corresponde a void
• open: se reabrió manualmente el cobro de una factura que estaba en revisión, desde el dashboard o por API

El estado overdue aparece en el tipo del campo status pero no genera este webhook hoy.

Factura pagada

{
  "eventType": "INVOICE_UPDATE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "active",
    "externalId": "EXT123456"
  },
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "paid",
    "total": "3907.85",
    "amountDue": "0",
    "totalUsd": "5.79",
    "exchangeRate": "674.9305"
  }
}

Factura incobrable

{
  "eventType": "INVOICE_UPDATE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "uncollectible",
    "total": "3907.85",
    "amountDue": "3907.85",
    "totalUsd": "5.79",
    "exchangeRate": "674.9305"
  }
}

Fíjate en lo que no está: no hay objeto subscription. Es a propósito, y pasa siempre en este estado, aunque la factura sea de una suscripción.

Factura anulada

{
  "eventType": "INVOICE_UPDATE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "active",
    "externalId": "EXT123456"
  },
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "cancelled",
    "total": "3907.85",
    "amountDue": "3907.85",
    "totalUsd": "5.79",
    "exchangeRate": "674.9305"
  }
}

amountDue refleja el saldo pendiente al momento de la anulación, ya que anular una factura no la marca como cobrada. A partir de ese momento, la factura no se cobra ni se considera deuda.

Factura reabierta

Se envía cuando una factura en revisión vuelve a estar disponible para cobro:

{
  "eventType": "INVOICE_UPDATE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "status": "active",
    "externalId": "EXT123456"
  },
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "open",
    "total": "3907.85",
    "amountDue": "3907.85",
    "totalUsd": "5.79",
    "exchangeRate": "674.9305"
  }
}

Si posteriormente se confirma el cobro pendiente o la factura se cobra en un nuevo intento, recibirás también los eventos de pago habituales: PAYMENT_SUCCESS_EVENT y INVOICE_UPDATE_EVENT con estado paid.

En ambos casos, el objeto subscription puede no incluirse aunque la factura pertenezca a una suscripción (ver la tabla anterior).

Moneda: total y amountDue van en VES (Bs); totalUsd es el mismo total en USD (independiente de la tasa BCV) y exchangeRate es la tasa BCV que los relaciona (total ≈ totalUsd × exchangeRate). totalUsd y exchangeRate pueden ser null si no están disponibles, y en ese caso lo son los dos: nunca llega una tasa sin su monto en dólares, ni al revés.

PAYMENT_SUCCESS_EVENT

Se envía cuando un pago se completa exitosamente. Si el pago se originó desde una sesión de checkout, incluye los datos de la sesión y su metadata.

{
  "eventType": "PAYMENT_SUCCESS_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "payment": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "status": "completed",
    "retries": 1,
    "gatewayUUID": "TXN000000123456",
    "bankReference": "003812449021",
    "errorMessage": null,
    "bank": "Banco Nacional de Crédito",
    "amount": "3907.85",
    "amountUsd": "5.79",
    "exchangeRate": "674.9305",
    "paymentMethod": "domiciliado"
  },
  "session": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "metadata": {
      "order_id": "ORD-12345",
      "campaign": "summer_promo"
    }
  }
}

Campos de payment

Los dos viajan juntos: o amountUsd y exchangeRate llegan los dos con valor, o llegan los dos en null — la misma regla que en PAYMENT_FAILED_EVENT. Y la tasa viene congelada en la factura, no es la del día: si conviertes amountUsd con la tasa de hoy te va a dar otro número.

Valores de paymentMethod

Lista cerrada: trata paymentMethod como una lista de valores fijos. Si en el futuro se agrega una vía nueva, se anunciará antes de empezar a enviarla.

No confundir con el API REST: en el API REST, payment_method es el ID (UUID) del método de pago guardado del cliente. El paymentMethod de este webhook es otra cosa: la vía por la que entró el dinero.

Solo en pagos exitosos: por ahora, paymentMethod solo viene en PAYMENT_SUCCESS_EVENT. PAYMENT_FAILED_EVENT no lo incluye.

Campos de session (opcional)

Nota: El campo session solo está presente en pagos que se originan desde una sesión de checkout. Los pagos recurrentes de suscripciones no incluyen este campo.

PAYMENT_FAILED_EVENT

Se envía cuando un pago falla. Puede ocurrir en múltiples etapas del procesamiento (validación, cobro de suscripción, verificación). Es posible recibir múltiples eventos de fallo para la misma transacción si hay reintentos.

{
  "eventType": "PAYMENT_FAILED_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "payment": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "status": "failed",
    "retries": 2,
    "gatewayUUID": "TXN000000123456",
    "bankReference": "003812449021",
    "errorMessage": "Insufficient funds",
    "bank": "Banco Nacional de Crédito",
    "amount": "3907.85",
    "amountUsd": "5.79",
    "exchangeRate": "674.9305"
  },
  "session": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "metadata": {
      "order_id": "ORD-12345",
      "campaign": "summer_promo"
    }
  }
}

Nota: Al igual que PAYMENT_SUCCESS_EVENT, el campo session solo está presente cuando el pago se origina desde una sesión de checkout.

Campos del plan de reintentos (solo en cobros recurrentes)

Cuando el fallo ocurre cobrando una suscripción ya activa, el evento trae además estos dos campos. No aparecen en los fallos de checkout ni en los cobros de validación.

{
  "eventType": "PAYMENT_FAILED_EVENT",
  "client": { "...": "..." },
  "payment": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "status": "failed",
    "errorMessage": "Insufficient funds",
    "attemptCount": 2,
    "nextPaymentAttempt": "2026-10-04T09:00:00.000Z"
  }
}

Si te interesa avisarle al cliente antes de perder la suscripción, nextPaymentAttempt: null es la señal: es el último fallo antes de la cancelación.

Moneda: amount es lo que se intentó cobrarle al banco, en VES (Bs). amountUsd es ese mismo monto en USD, tal como quedó guardado en la factura. exchangeRate es la tasa BCV que los relaciona: amount ≈ amountUsd × exchangeRate.

La tasa viene congelada en la factura, no es la del día. Es la tasa con la que se calculó ese cobro. Si conviertes amountUsd con la tasa de hoy te va a dar otro número: usa siempre el exchangeRate que llega en el evento. Esto es a propósito.

Cuándo llegan en null: amountUsd y exchangeRate vienen en null en tres casos. Uno, facturas viejas creadas antes de que existiera la columna en dólares. Dos, los cobros de validación — el cargo de prueba de Bs 1,00 que confirma que una cuenta bancaria existe, que no tiene factura ni precio en dólares detrás. Tres, un fallo tan temprano que la factura todavía no existía; ahí amount llega en "0". Nunca llega una tasa sin su monto en dólares, ni un monto en dólares sin su tasa: o vienen los dos con valor, o vienen los dos en null.

Corrección — amount en el primer cobro de un checkout de suscripción. Ese caso puntual traía el precio del plan, que está en dólares, mientras todos los demás traían bolívares. Era un error y quedó corregido: amount ahora trae bolívares siempre.

Esto no cambia ningún cobro. No cambia cuánto se le cobra al cliente, ni los correos que recibe, ni el evento de pago exitoso. Cambia un solo dato, de este evento, en este escenario.

Qué hacer: si tu integración lee amount como dólares en un fallo de checkout, ajústala — una suscripción de USD 5,79 pasa de "5.79" a "3907.85". Si ya lo tratabas como bolívares, no tienes nada que hacer: hasta ahora recibías un dato incorrecto en ese caso y ahora recibes el correcto. El monto en dólares no se pierde, viaja en amountUsd, y con exchangeRate al lado puedes reconstruir el valor anterior dividiendo.

PAYMENT_REMINDER_PRE_EVENT

Se envía cuando Venflow le recuerda al cliente que se acerca la fecha de cobro, según los recordatorios configurados en tu organización, y solo si ese recordatorio tiene activado el canal de webhook. Sirve para avisarle al cliente también por tus propios canales.

A diferencia del resto de los eventos de cliente, no incluye el objeto subscription: el recordatorio describe una fecha de cobro, no un cambio en la suscripción.

{
  "eventType": "PAYMENT_REMINDER_PRE_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "reminder": {
    "type": "pre_payment",
    "daysOffset": 3,
    "billingDate": "2026-10-01 00:00:00+00"
  }
}

PAYMENT_REMINDER_POST_EVENT

Mismo formato que el anterior, pero para recordatorios posteriores: después de un cobro fallido, o para un pago manual que sigue pendiente.

{
  "eventType": "PAYMENT_REMINDER_POST_EVENT",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "cliente@email.com",
    "name": "Juan",
    "lastName": "Pérez"
  },
  "reminder": {
    "type": "post_failure",
    "daysOffset": 2,
    "billingDate": "2026-10-01 00:00:00+00"
  }
}

Campos de reminder

Estos eventos no incluyen los objetos subscription, invoice ni payment.

GATEWAY_API_KEY_EXPIRING_EVENT

Evento a nivel de organización. Se envía cuando la API key del gateway de pago está próxima a vencer, como recordatorio para que la organización renueve sus credenciales antes de que dejen de funcionar.

Se emite por cada umbral de aviso configurado (por defecto 3 días y 1 día antes del vencimiento). Cada umbral se envía una sola vez por ventana de vencimiento; al renovar la key, los avisos vuelven a habilitarse para el nuevo período.

{
  "eventType": "GATEWAY_API_KEY_EXPIRING_EVENT",
  "organizationId": "wc8opaq1y1j5",
  "configId": "550e8400-e29b-41d4-a716-446655440000",
  "bankId": "660e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2026-07-16T16:16:19.742Z",
  "daysRemaining": 3
}

Campos

Nota: El payload nunca incluye la apiKey ni el apiSecret.

GATEWAY_API_KEY_EXPIRED_EVENT

Evento a nivel de organización. Se envía cuando la API key del gateway ya venció y el sistema la desactivó automáticamente. A partir de este momento, la organización no podrá procesar cobros hasta cargar credenciales nuevas.

{
  "eventType": "GATEWAY_API_KEY_EXPIRED_EVENT",
  "organizationId": "fse0srailt3v",
  "configId": "550e8400-e29b-41d4-a716-446655440000",
  "bankId": "660e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2026-06-12T17:47:13.325Z"
}

Campos

Nota: El payload nunca incluye la apiKey ni el apiSecret. Además del webhook, la organización recibe un email a sus administradores y el equipo de Venflow recibe un aviso interno por Slack.

Orden de Eventos en un Checkout

Durante un flujo de checkout típico, los eventos se emiten en este orden:

1. USER_CREATE_EVENT          → Cliente creado (solo si es nuevo)
2. SUBSCRIPTION_CREATE_EVENT  → Suscripción activada
3. INVOICE_CREATE_EVENT       → Factura generada
4. PAYMENT_SUCCESS_EVENT      → Pago completado
5. INVOICE_UPDATE_EVENT       → Factura marcada como pagada

Flujo de Error

• PAYMENT_FAILED_EVENT puede ocurrir en cualquier etapa del procesamiento de pago
• Se pueden recibir múltiples PAYMENT_FAILED_EVENT para la misma transacción (reintentos)
• Si el cobro falla definitivamente, se envía INVOICE_UPDATE_EVENT con estado uncollectible seguido de SUBSCRIPTION_CANCELLED_EVENT con razón payment_failure

Valores de Estado

Qué significa cada estado de suscripción