Tipos de eventos de webhook

El catálogo completo de eventos de webhook de Tokeflow para pagos, reembolsos, disputas, métodos de pago y suscripciones, con un payload de ejemplo.

Tokeflow emite un evento cada vez que ocurre algo relevante en una transacción, un reembolso, una disputa, un método de pago almacenado o una suscripción. Suscribe tu endpoint a los eventos que te interesen (puedes filtrar por tipo cuando configuras el endpoint) y luego reacciona a ellos como la fuente de verdad para los resultados asíncronos.

Cada evento se entrega en el sobre estándar descrito en Descripción general de webhooks y se firma como se describe en Verificación de firmas. El campo type contiene uno de los valores siguientes.

Trata los eventos de forma idempotente. Deduplica según el id del evento y, cuando un evento cambie un estado importante, concilia contra la API (por ejemplo, GET /api/v1/transactions/:id) antes de actuar. Los eventos pueden llegar fuera de orden o más de una vez.

Eventos de transacción

Event	Cuándo se dispara
`transaction.created`	Se creó una transacción y se aceptó para su procesamiento.
`transaction.pending`	El cargo está esperando un resultado asíncrono (por ejemplo, PIX, boleto).
`transaction.pre_authorized`	Se autorizaron los fondos pero no se capturaron (`capture: false`).
`transaction.authorized`	El cargo tuvo éxito (autorizado y capturado, salvo que sea solo preautorización).
`transaction.capture_pending`	Se solicitó una captura y se está procesando.
`transaction.failed`	El cargo fue rechazado o no se pudo completar.
`transaction.canceled`	La transacción se canceló antes de completarse.
`transaction.voided`	Se anuló una autorización antes de la captura.
`transaction.charged_back`	Se abrió un contracargo contra la transacción.
`transaction.expired`	Un cargo pendiente expiró sin completarse (por ejemplo, PIX/boleto no pagado a tiempo).

Eventos de reembolso

Event	Cuándo se dispara
`transaction.refund_created`	Se creó un reembolso.
`transaction.refund_pending`	El reembolso está siendo procesado por el proveedor.
`transaction.refunded`	La transacción fue reembolsada por completo.
`transaction.partially_refunded`	Se liquidó un reembolso parcial; queda un saldo capturado.
`transaction.refund_failed`	El reembolso no se pudo completar.
`transaction.refund_cancelled`	Se canceló un reembolso pendiente.

Eventos de disputa

Event	Cuándo se dispara
`transaction.dispute_created`	El banco del titular de la tarjeta abrió una disputa.
`transaction.dispute_updated`	Nueva información o un cambio de estado en una disputa abierta.
`transaction.dispute_won`	La disputa se resolvió a tu favor.
`transaction.dispute_lost`	La disputa se resolvió en tu contra.
`transaction.dispute_closed`	La disputa se cerró.

Eventos de método de pago

Event	Cuándo se dispara
`payment_method.action_required`	Un método de pago almacenado requiere atención — por ejemplo, una tarjeta reportada como ya no válida o sin reemplazo disponible en la red. Solicita al cliente que la actualice.

Eventos de suscripción

Event	Cuándo se dispara
`subscription.created`	Se creó una suscripción.
`subscription.renewed`	Un cargo de renovación tuvo éxito y la suscripción avanzó al siguiente período.
`subscription.dunning`	Un cargo de renovación falló; la suscripción entró en cobranza (reintentos).
`subscription.reactivated`	Una suscripción volvió a `active` tras la cobranza o una pausa.
`subscription.upgraded`	La suscripción pasó a una oferta de mayor valor.
`subscription.downgraded`	La suscripción pasó a una oferta de menor valor.
`subscription.payment_method_changed`	Se cambió el instrumento de pago de la suscripción.
`subscription.paused`	La suscripción se pausó.
`subscription.resumed`	Una suscripción pausada se reanudó.
`subscription.cancelled`	La suscripción se canceló.
`subscription.expired`	La suscripción llegó al final de su plazo y expiró.

Payload de ejemplo

Un evento transaction.authorized. El recurso reside en data.object:

{
  "id": "evt_3f9a2b1c8d7e",
  "type": "transaction.authorized",
  "created_at": "2026-01-15T12:30:09.000Z",
  "data": {
    "object": {
      "id": "tx_777",
      "organization_id": "org_123",
      "merchant_id": "mrc_123",
      "order_id": "ord_001",
      "external_order_id": "order_888",
      "customer_id": "cust_123",
      "amount_authorized": 15000,
      "amount_captured": 15000,
      "currency": "BRL",
      "payment_method": "credit_card",
      "charge_type": "payment",
      "country": "BR",
      "status": "authorized",
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:09.000Z"
    }
  }
}

La forma de data.object coincide con el recurso de la API correspondiente — una transacción para los eventos transaction.*, un reembolso para los eventos de reembolso, una suscripción para los eventos subscription.*, etc. Consulta la referencia de la API para ver el esquema completo de cada objeto.

Guía de manejo

Confirma rápido. Devuelve un 2xx en unos pocos segundos y realiza el trabajo real de forma asíncrona. Las respuestas lentas o fallidas provocan reintentos.
Deduplica según el id. El mismo evento puede entregarse más de una vez.
No confíes en el orden. Usa el propio status del recurso (o una lectura fresca de la API) en lugar de asumir que los eventos llegan en secuencia.
Verifica cada entrega. Rechaza cualquier solicitud cuya firma no se valide — consulta Verificación de firmas.