> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/webhooks/eventos-de-suscripciones.md).

# 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:

<table><thead><tr><th width="190.03515625">Estado</th><th>Descripción</th></tr></thead><tbody><tr><td>ACTIVE<br><code>Activa</code></td><td>Cuando el cliente completa la vinculación del medio de pago.</td></tr><tr><td>OVERDUE<br><code>Vencida</code></td><td>Cuando se agotan los reintentos configurados en el Plan sin lograr el cobro. Si aplica en el plan.</td></tr><tr><td>CANCELED<br><code>Cancelada</code></td><td>Cuando la suscripción se cancela automáticamente al agotar reintentos, o manualmente vía API o desde la vista del cliente.</td></tr><tr><td>FULFILLED<br><code>Completada</code></td><td>Cuando la suscripción alcanza el número total de cobros pactado en el Plan.</td></tr></tbody></table>

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

{% hint style="info" %}
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.
{% endhint %}

## Encabezado

<table><thead><tr><th width="232.5999755859375">Nombre</th><th>Contenido</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Bearer {auth_key}</td></tr><tr><td><code>Content-Type</code></td><td>application/json</td></tr></tbody></table>

## Payload

{% code overflow="wrap" %}

```json
{
    "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": "cliente@correo.com",
            "phone": "573001234567",
            "name": "Juan Pérez"
        },
        "form_field_values": {
            "field_one": "Juan Pérez",
            "field_two": "cliente@correo.com"
        },
        "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"
    }
}
```

{% endcode %}

{% hint style="info" %}
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.
{% endhint %}