Cómo usar webhooks con suscripciones

Aprende a usar webhooks para recibir notificaciones de actividad en las suscripciones.

Recibes notificaciones de Stripe en tu aplicación a través de eventos webhook. Usa eventos de webhook para administrar suscripciones, ya que la mayor parte de la actividad se produce de forma asíncrona. Procesa estos eventos en un punto de conexión de webhook o en otros destinos, como Amazon EventBridge, mediante la creación de un destino de evento.

Para usar webhooks con tus suscripciones:

Crea un punto de conexión de webhook en tu aplicación.
Registra tu punto de conexión de webhook en Workbench
Agrega lógica para gestionar los eventos de Stripe. En el caso de las suscripciones, se incluyen los errores de pago y los cambios en el estado de la suscripción (como pasar de un estado de prueba a uno activo). Puedes usar la guía de inicio rápido de webhook para crear un punto de conexión de webhook mínimo.
Prueba el punto de conexión del webhook para confirmar que funciona según lo previsto.

Si tu aplicación se ejecuta en AWS, puedes configurar Stripe para enviar eventos directamente a AWS EventBridge en tu cuenta de AWS.

Eventos de suscripción

Stripe activa eventos cada vez que se crea o modifica una suscripción. Cuando se crea una suscripción, algunos eventos se envían de inmediato, mientras que otros se repiten conforme a intervalos regulares de cobro.

Asegúrate de que tu integración gestione correctamente los eventos. Por ejemplo, puedes enviar un correo electrónico a un cliente si falla un pago o revocar el acceso de un cliente cuando se cancela una suscripción.

En la siguiente tabla se describen los eventos más comunes relacionados con las suscripciones y, si corresponde, se sugieren acciones para controlar los eventos.



`customer.created`	Se envía cuando se crea correctamente un objeto Customer.
`customer.subscription.created`	Se envía cuando se crea la suscripción. El `status` de la suscripción puede ser `incomplete` si se exige la autenticación del cliente para completar el pago o si estableces `payment_behavior` en `default_incomplete`. Consulta el comportamiento del pago de la suscripción para obtener más información.
`customer.subscription.deleted`	Se envía cuando se termina la suscripción de un cliente.
`customer.subscription.paused`	Se envía cuando el `status` de una suscripción cambia a `paused`. Por ejemplo, se envía cuando una suscripción está configurada para pausarse cuando una prueba gratuita finaliza sin un método de pago. La facturación no se producirá hasta que se reanude la suscripción. No enviamos este evento si el cobro del pago está pausado porque las facturas se siguen creando durante ese período.
`customer.subscription.resumed`	Se envía cuando se reanuda una suscripción que anteriormente estaba en estado `paused`. Esto no se aplica cuando el cobro del pago no está en pausa.
`customer.subscription.trial_will_end`	Se envía tres días antes de que finalice el período de prueba. Si el periodo de prueba es menor de tres días, este evento se activa.
`customer.subscription.updated`	Se envía cuando se inicia o cambia una suscripción. Por ejemplo, este evento se activa cuando se renueva una suscripción, se agrega un cupón, se aplica un descuento, se agrega una partida de factura o se cambia de plan.
`entitlements.active_entitlement_summary.updated`	Se envía cuando se actualizan los derechos activos de un cliente. Cuando recibas este evento, puedes proporcionar o anular el acceso a las funciones de tu producto. Lee más sobre integración con derechos.
`invoice.created`	Se envía cuando se crea una factura para una suscripción renovada o una nueva. Si Stripe no recibe una respuesta correcta al evento `invoice.created`, la finalización de todas las facturas con cobro automático se retrasará hasta 72 horas. Obtén más información sobre cómo finalizar facturas. Para responder a la notificación, envía una solicitud a la API Finalize an invoice.
`invoice.finalized`	Se envía cuando una factura se finaliza correctamente y está lista para pagarse. Puedes enviar la factura al cliente. Consulta la finalización de la factura para obtener más información. Según tu configuración, cobramos automáticamente al método de pago predeterminado o intentamos el cobro. Consulta los correos electrónicos posteriores a la finalización para obtener más información.
`invoice.finalization_failed`	No se pudo finalizar la factura. Lee la guía y aprende a gestionar los fallos de finalización de facturas. Obtén más información sobre la finalización de facturas en la guía resumida sobre facturas. Inspecciona el last_finalization_error del objeto Invoice para determinar la causa del error. Si usas Stripe Tax, revisa el campo automatic_tax del objeto Invoice. Si `automatic_tax[status]=requires_location_inputs`, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y recopila la ubicación del cliente requerida. Si `automatic_tax[status]=failed`, reintenta la solicitud más tarde.
`invoice.paid`	Se envía cuando la factura se paga correctamente. Puedes brindar acceso a tu producto cuando recibas este evento y el `status` de la suscripción sea `active`.
`invoice.payment_action_required`	Se envía cuando la factura requiere la autenticación del cliente. Aprende a gestionar la suscripción cuando la factura requiere intervención.
`invoice.payment_failed`	Falló el pago de una factura. El estado del PaymentIntent cambia a `requires_action`, mientras que el de la suscripción sigue siendo `incomplete` solo en la primera factura. Si falla un pago, puedes tomar varias medidas: Notifica al cliente. Obtén más información sobre cómo puedes configurar los parámetros de suscripción para habilitar Smart Retries y otras funcionalidades de recuperación de ingresos. Si estás usando PaymentIntents, recopila la nueva información de pago y confirma el PaymentIntent. Actualiza el método de pago predeterminado en la suscripción.
`invoice.upcoming`	Se envía unos días antes de la renovación de la suscripción. La cantidad de días se basa en el número establecido en Próximos eventos de renovación en el Dashboard. Para las suscripciones existentes, el cambio del número de días entrará en vigencia en el siguiente período de facturación. De ser necesario, aún puedes agregar más partidas de factura.
`invoice.updated`	Se envía tanto cuando un pago falla como cuando se efectúa correctamente. Si sucede esto último, el atributo `paid` se establece en `true` y el `status` será `paid`. Si el pago falla, `paid` se establece en `false` y el `status` permanecerá `open`. Los pagos fallidos también activan el evento `invoice.payment_failed`.
`payment_intent.created`	Se envía cuando se crea una PaymentIntent.
`payment_intent.succeeded`	Se envía cuando un PaymentIntent ha completado correctamente un pago.
`subscription_schedule.aborted`	Se envía cuando se cancela un calendario de suscripciones porque el retraso en el pago canceló la suscripción relacionada.
`subscription_schedule.canceled`	Se envía cuando se cancela un calendario de suscripciones, lo que también cancela las suscripciones asociadas activas.
`subscription_schedule.completed`	Se envía cuando se completan todas las fases de un calendario de suscripciones.
`subscription_schedule.created`	Se envía cuando se crea un nuevo calendario de suscripciones.
`subscription_schedule.expiring`	Se envía siete días antes de que expire el calendario de suscripción.
`subscription_schedule.released`	Se envía cuando se lanza un calendario de suscripción, o cuando se pausa y desvincula dicho calendario de la suscripción. La suscripción permanece.
`subscription_schedule.updated`	Se envía cuando se actualiza un calendario de suscripciones.

Gestionar pagos fallidos

Los eventos le proporcionan a Stripe una forma confiable de notificar los errores de pago en las facturas de suscripciones. Algunos errores en el pago son temporales; por ejemplo, el emisor de una tarjeta puede rechazar el cargo inicial, pero permitir un reintento automático. Otros errores en el pago son definitivos y requieren acción, como no tener un método de pago utilizable para el cliente.

Evento Descripción

Evento	Descripción
`invoice.payment_failed`	Falló el pago de una factura. El estado del PaymentIntent cambia a `requires_payment_method`. El estado de la suscripción cambia a `incomplete`. Si se produce un error en un pago, hay varias medidas que se pueden tomar: Notifica al cliente. Si estás usando PaymentIntents, recopila la nueva información de pago y confirma el PaymentIntent. Actualiza el default payment method en la suscripción. Considera habilitar Smart Retries.

invoice.payment_failed

Falló el pago de una factura. El estado del PaymentIntent cambia a requires_payment_method. El estado de la suscripción cambia a incomplete. Si se produce un error en un pago, hay varias medidas que se pueden tomar:

Notifica al cliente.
Si estás usando PaymentIntents, recopila la nueva información de pago y confirma el PaymentIntent.
Actualiza el default payment method en la suscripción.
Considera habilitar Smart Retries.

Gestionar pagos que requieren una acción adicional

Es posible que algunos métodos de pago deban cumplir con pasos adicionales, como la autenticación del cliente. Si recibes estos eventos, tu aplicación tendrá que solicitarle al cliente que lleve a cabo la acción requerida. Para obtener detalles sobre cómo gestionar eventos que requieren acciones adicionales, lee la guía resumida sobre suscripciones.

Evento Descripción

Evento	Descripción
`invoice.finalization_failed`	No se pudo finalizar la factura. Lee la guía y aprende a gestionar los fallos de finalización de facturas. En la guía resumida sobre facturas, encontrarás más información la finalización de facturas. Inspecciona el last_finalization_error del objeto Invoice para determinar la causa del error. Si usas Stripe Tax, revisa el campo automatic_tax del objeto Invoice. Si `automatic_tax[status]=requires_location_inputs`, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y recopila la ubicación del cliente. requerida. Si `automatic_tax[status]=failed`, vuelve a intentar la solicitud más tarde.
`invoice.payment_failed`	Falló el pago de una factura. El estado de PaymentIntent cambia a `requires_action`. El estado de la suscripción cambia a `incomplete`. Si se produce un error en un pago, hay varias medidas que se pueden tomar: Notifica al cliente. Si estás usando PaymentIntents, recopila la nueva información de pago y confirma el PaymentIntent. Actualiza el default payment method en la suscripción. Considera habilitar Smart Retries.
`invoice.payment_action_required`	Falló el pago de una factura. El estado de PaymentIntent cambia a `requires_action`. El estado de la suscripción cambia a `incomplete`. Si se produce un error en un pago, hay varias medidas que se pueden tomar: Notifica al cliente. Si estás usando PaymentIntents, recopila la nueva información de pago y confirma el PaymentIntent. Actualiza el default payment method en la suscripción. Considera habilitar Smart Retries.

invoice.finalization_failed

No se pudo finalizar la factura. Lee la guía y aprende a gestionar los fallos de finalización de facturas. En la guía resumida sobre facturas, encontrarás más información la finalización de facturas.

Inspecciona el last_finalization_error del objeto Invoice para determinar la causa del error.
Si usas Stripe Tax, revisa el campo automatic_tax del objeto Invoice.
Si automatic_tax[status]=requires_location_inputs, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y recopila la ubicación del cliente. requerida.
Si automatic_tax[status]=failed, vuelve a intentar la solicitud más tarde.

invoice.payment_failed

Falló el pago de una factura. El estado de PaymentIntent cambia a requires_action. El estado de la suscripción cambia a incomplete. Si se produce un error en un pago, hay varias medidas que se pueden tomar:

Notifica al cliente.
Si estás usando PaymentIntents, recopila la nueva información de pago y confirma el PaymentIntent.
Actualiza el default payment method en la suscripción.
Considera habilitar Smart Retries.

invoice.payment_action_required

Notifica al cliente.
Si estás usando PaymentIntents, recopila la nueva información de pago y confirma el PaymentIntent.
Actualiza el default payment method en la suscripción.
Considera habilitar Smart Retries.

Hacer el seguimiento de suscripciones activas

Las suscripciones requieren coordinación entre tu sitio y Stripe. El éxito o el fracaso de los pagos recurrentes de un cliente determina si puede seguir accediendo a tu producto o servicio.

En las integraciones típicas, almacenas las credenciales de los clientes y un valor de marca de tiempo asignado que representa la fecha de vencimiento del acceso de ese cliente en tu sitio cuando se suscribe. Cuando el cliente inicia sesión, compruebas si la marca de tiempo aún está con fecha futura. De ser así, la cuenta está activa y el cliente aún debería tener acceso al servicio.

Cuando se renueva la suscripción, Stripe factura al cliente e intenta cobrar el pago mediante el cobro automático del método de pago registrado o enviando la factura por correo electrónico a los clientes. Stripe notifica a tu sitio el estado de la factura mediante el envío de un evento de webhook:

Tu sitio recibe un evento invoice.paid.
- Cuando se cobra automáticamente un método de pago, tu sitio recibe primero un evento invoice.upcoming en tu punto de conexión de webhook configurado unos días antes de la renovación. Puedes escuchar este evento para agregar elementos de factura adicionales a la próxima factura. Si collection_method=send_invoice, Stripe no envía un evento invoice.upcoming.
La aplicación encuentra el cliente para el que se realizó el pago.
La aplicación actualiza la fecha de vencimiento del acceso del cliente en la base de datos a la fecha adecuada en el futuro (más uno o dos días de margen de maniobra).

Captar los cambios de estado de las suscripciones

Asegúrate de que tu integración gestione y controle de forma correcta las transiciones entre los estados de suscripción descritos en la tabla a continuación.

Algunos cambios de estado necesitan atención especial:

Unos días antes de que finalice una prueba y la suscripción pase de trialing a active, recibirás un evento customer.subscription.trial_will_end. Cuando recibas este evento, verifica que tienes un método de pago del cliente para poder facturarle. Opcionalmente, notifica al cliente que se le cobrará.
Cuando una suscripción pasa a past_due, notifica directamente al cliente y solicítale que actualice sus datos de pago. Stripe ofrece varias funcionalidades que ayudan a automatizar este proceso. Obtén más información sobre la recuperación de ingresos.
Cuando una suscripción cambia a canceled o unpaid, revoca el acceso a tu producto.

Estado	Descripción
`trialing`	La suscripción actualmente está dentro de un período de prueba y puedes suministrar el producto a tu cliente de forma segura. La suscripción pasará automáticamente a `active` cuando un cliente efectúe el primer pago.
`active`	La suscripción está en regla. En el caso de las suscripciones `past_due`, pagar la última factura asociada o marcarla como incobrable hace que la suscripción pase a `active`. Ten en cuenta que `active` no indica que se hayan pagado todas las facturas pendientes asociadas con la suscripción. Puedes dejar otras facturas pendientes abiertas para su pago, marcarlas como incobrables o anularlas como mejor te parezca.
`incomplete`	El cliente debe realizar un pago correctamente en el transcurso de 23 horas para activar la suscripción. O bien, el pago requiere acción, como la autenticación del cliente. Las suscripciones también pueden mostrarse como `incomplete` si hay un pago pendiente y el estado de PaymentIntent es `processing`.
`incomplete_expired`	Se produjo un error en el pago inicial de la suscripción y el cliente no efectuó ningún pago correctamente procesado en el transcurso de 23 horas de creada la suscripción. Estas suscripciones no se cobran a los clientes. Este estado existe para que puedas hacer el seguimiento de los clientes que no pudieron activar sus suscripciones.
`past_due`	No se intentó pagar la última factura finalizada o falló el pago\|. La suscripción sigue generando facturas. Tu configuración de suscripciones determina el próximo estado de la suscripción. Si la factura sigue no pagada después de todos los intentos de Smart Retries, puedes configurar la suscripción de modo que pase a `canceled` o `unpaid`. o dejarla como `past_due`. Para reactivar la suscripción, pídele a tu cliente que pague la factura más reciente. El estado de la suscripción pasa a `active` independientemente de si el pago se realiza antes o después de la última fecha de vencimiento de la factura.
`canceled`	Se canceló la suscripción. Mientras esté cancelada, se deshabilita el cobro automático de todas las facturas no pagadas (`auto_advance=false`). Este estado es final y no puede actualizarse.
`unpaid`	No se abonó la última factura, pero la suscripción sigue vigente. La última factura permanece abierta y las facturas se siguen generando, pero no se intenta hacer pagos. Revoca el acceso a tu producto cuando la suscripción tenga el estado `unpaid` porque los pagos ya se intentaron y reintentaron mientras la suscripción estaba en estado `past_due`. Para que la suscripción pase a `active`, paga la factura más reciente antes de la fecha de vencimiento.
`paused`	La suscripción finalizó su período de prueba sin un método de pago predeterminado y el trial_settings.end_behavior.missing_payment_method está configurado en `pause`. Ya no se crean facturas para la suscripción. Después de asociar un método de pago predeterminado al cliente, puedes reanudar la suscripción.

Puntos de conexión de webhook y facturas

Registra un punto de conexión de webhooks para hacer un seguimiento de los estados de las facturas. La integración de tu suscripción depende de finalizar correctamente las facturas y gestionar adecuadamente los errores de finalización de facturas.

Cuando habilitas el cobro automático, Stripe finaliza automáticamente y da inicio al cobro automático de la factura…

Si Stripe no recibe una respuesta correcta al evento invoice.created, retrasaremos la finalización de todas las facturas con cobro automático hasta 72 horas, salvo aquellas en las que hayas establecido una hora de finalización programada personalizada.
Una respuesta adecuada al evento invoice.created incluye la gestión de todos los puntos de conexión de webhooks configurados para tu cuenta y para cualquier plataforma con la que te hayas conectado. Estas no incluyen ningún punto de conexión de webhook configurado en una organización. Si bien puedes recibir notificaciones de eventos invoice.created en la organización, una respuesta correcta no afecta la finalización de la factura cuando se usa el cobro automático.
Si se actualiza una suscripción de forma que se intenta el pago de manera sincrónica (en la factura inicial y en algunos tipos de actualizaciones), no se da esta espera.
La falla en la finalización de la factura evita el cobro del pago de la factura. Asegúrate de recibir notificaciones de eventos invoice.finalization_failed en tu punto de conexión de webhooks.

Consulta una lista completa de los tipos de eventos de factura.

Evento	Descripción
`invoice.created`	La factura se creó correctamente y está lista para finalizarse. Lee la documentación para aprender más sobre cómo finalizar facturas. Para responder a la notificación, envía una solicitud a la API Finalize an invoice.
`invoice.finalized`	La factura se finalizó correctamente y está lista para pagarse. Puedes enviar la factura al cliente. Obtén más información sobre la finalización de facturas. Según tu configuración, Stripe cobra automáticamente al método de pago predeterminado o intenta el cobro. Obtén más información sobre los correos electrónicos posteriores a la finalización.
`invoice.finalization_failed`	No se pudo finalizar la factura. Lee la guía y aprende a gestionar los fallos de finalización de facturas. Obtén más información sobre la finalización de facturas en la guía resumida sobre facturas. Inspecciona el last_finalization_error del objeto Invoice para determinar la causa del error. Si usas Stripe Tax, revisa el campo automatic_tax del objeto Invoice. Si `automatic_tax[status]=requires_location_inputs`, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y recopila la ubicación del cliente requerida. Si `automatic_tax[status]=failed`, reintenta la solicitud más tarde.

Finalización correcta de una factura

Stripe espera una hora después de recibir una respuesta correcta al evento invoice.created antes de intentar el pago. Si no recibimos ninguna respuesta correcta en el término de 72 horas, intentaremos finalizar la factura y enviarla.

Si quieres procesar las facturas puntuales de manera distinta a las facturas de suscripciones, revisa la propiedad subscription en el cuerpo del webhook. Esto indica si la factura fue creada para una suscripción.

En modo activo, si el punto de conexión de webhooks no responde adecuadamente, Stripe sigue reintentando la notificación de webhooks hasta por 3 días con un retroceso exponencial. En un entorno de prueba, reintentamos tres veces en el transcurso de unas horas. Durante ese período, no intentaremos cobrarle al cliente a menos que recibamos una respuesta correcta. También te notificaremos por correo electrónico que el webhook está devolviendo un error.

Este comportamiento se aplica a todos los puntos de conexión de webhooks definidos en tu cuenta, incluidos aquellos casos en que una aplicación de Connect u otro servicio de terceros tenga problemas para gestionar webhooks entrantes.

Fallo en la finalización de una factura

Si Stripe no puede finalizar una factura, se envía un evento invoice.finalization_failed a tu punto de conexión de webhooks. Si las facturas no se pueden finalizar, las suscripciones permanecen activas, por lo que es posible que los usuarios sigan teniendo acceso a tu producto, pero tú no puedas cobrar los pagos. Asegúrate de tomar medidas sobre las facturas que devuelven un error en la finalización. No puedes cobrar los pagos de una factura que no esté finalizada.

Para determinar por qué falló la finalización de la factura, revisa el campo last_finalization_error del objeto Invoice. Este campo proporciona más información sobre el error y cómo proceder.

Si usas Stripe Tax, comprueba si el campo automatic_tax.status es requires_location_inputs, lo que indica que los datos de la dirección no son válidos o no son suficientes. Si Stripe Tax no puede encontrar una ubicación de cliente reconocida, no podemos finalizar la factura. Aprende a gestionar los errores en la finalización de facturas.

Pruebas

Para probar tu punto de conexión de webhooks o destino de evento, elige una de estas dos opciones:

Ejecuta acciones en un entorno de prueba que envíen eventos legítimos al destino de tu evento. Por ejemplo, para activar el evento charge.succeeded, puedes usar una tarjeta de prueba que dé como resultado un cargo efectuado con éxito.
Activa eventos con la CLI de Stripe o con Stripe para Visual Studio Code.