Eventos de suscripciones

En estos eventos, te notificaremos cada vez que ocurra una transición de estado en tus suscripciones. A diferencia de los eventos de cobros, que se notifican por cada intento individual, aquí solo recibirás un evento por cambio de estado del ciclo completo — los intentos de cobro dentro de una suscripción (éxito o fallo de cada Charge) se notifican por el webhook de cobros. Los estados que se notifican son los siguientes:

Estado	Descripción
ACTIVE Activa	Cuando el cliente completa la vinculación del medio de pago.
OVERDUE Vencida	Cuando se agotan los reintentos configurados en el Plan sin lograr el cobro. Si aplica en el plan.
CANCELED Cancelada	Cuando la suscripción se cancela automáticamente al agotar reintentos, o manualmente vía API o desde la vista del cliente.
FULFILLED Completada	Cuando la suscripción alcanza el número total de cobros pactado en el Plan.

Esto te permite mantener un control efectivo sobre tus suscripciones y reaccionar rápidamente ante cualquier eventualidad que pueda surgir.

Si configuraste un webhook personalizado a nivel de Plan (custom_webhook), los eventos de las suscripciones de ese plan se enviarán a esa URL en lugar del webhook global del comercio.

Encabezado

Nombre	Contenido
Authorization	Bearer {auth_key}
Content-Type	application/json

Payload

{
    "event": {
        "type": "subscription",
        "status": "activated"
    },
    "created_at": "2026-07-30 04:29:59.293",
    "external_reference": "6A5JHJY1C8Y",
    "detail": {
        "plan_id": "I6AZ4BFD41",
        "subscription_id": "6A5JHJY1C8Y",
        "status": "ACTIVE",
        "customer": {
            "id_number": "1020304050",
            "email": "[e-mail]",
            "phone": "573001234567",
            "name": "Juan Pérez"
        },
        "form_field_values": {
            "field_one": "Juan Pérez",
            "field_two": "[e-mail]"
        },
        "terms": {
            "currency": "COP",
            "amount": 150000,
            "description": "Cobro {{charge_number}} - {{month}}",
            "frequency": "monthly",
            "total_charges": 6,
            "retry": {
                "max_attempts": 3,
                "interval_days": 2,
                "final_status": "OVERDUE"
            }
        },
        "billing": {
            "charges_executed": 0,
            "charges_remaining": 6,
            "retries_used": 0,
            "next_charge_date": "2026-08-05"
        },
        "canceled_at": null,
        "created_at": "2026-07-29T19:17:28.378Z"
    }
}

El evento subscription.canceled incluye un campo adicional en detail: "reason": "retry_exhausted" cuando la cancelación fue automática por agotar reintentos, o "reason": "manual" cuando fue vía API o desde la vista del cliente. Ningún otro evento lleva este campo.