Suscripciones y eventos de pago mediante webhooks

Retrospectiva histórica: noviembre de 2025–agosto de 2026; cambios entre febrero y agosto de 2026

Este artículo se redactó posteriormente y describe cómo se amplió la función durante el periodo indicado. Los eventos de webhook evolucionaron desde el ciclo de vida básico de suscripciones hasta incluir reanudaciones, fallos de pago y resultados de pago. Consulta la guía de API pública y webhooks (Markdown-fil, AI-agentvenlig) para conocer la lista actual de eventos y el contrato.

Los webhooks notifican a un sistema externo cuando Alunta registra un cambio. Son útiles si un portal de clientes, CRM o sistema contable debe seguir las suscripciones sin consultar Alunta continuamente. Un evento es una señal sobre el estado de Alunta; no confirma que tu propio sistema haya completado la acción de seguimiento.

Eventos principales

El ciclo de vida puede incluir subscription.started, subscription.ended y subscription.resumed. Cancelar y finalizar son cosas distintas: cancelar puede programar o marcar que un acuerdo debe terminar, mientras que finalizar indica que la suscripción ya terminó. Más adelante se añadieron subscription.payment_succeeded y subscription.payment_failed para que una integración pueda reaccionar a cada resultado de pago. payment_succeeded confirma el pago en sí, pero un pago parcial o a plazos puede dejar saldo pendiente en la factura. Un evento invoice.paid describe el estado de pago de la factura y no se debe interpretar como prueba de que la suscripción esté activa.

Utiliza el tipo de evento documentado y la clave de deduplicación que se indique para ese tipo. subscription.started, subscription.ended, subscription.payment_succeeded e invoice.paid tienen un data.event_id estable para los reintentos y las repeticiones. subscription.payment_failed puede llegar varias veces debido a distintos intentos de reintento y no tiene un event_id estable; conserva cada entrega y utiliza el webhook_uuid documentado, cuando esté disponible, como clave de entrega. Suscríbete solo a los eventos que necesite la integración y consulta siempre la referencia actual de la API pública para los campos y valores de estado.

Primeros pasos

1. Activa para el equipo la capacidad de API y webhooks y configura un receptor HTTPS.
2. Registra el endpoint y selecciona los eventos necesarios de suscripción y pagos.
3. Verifica la firma con el cuerpo original de la solicitud antes de procesar la carga útil.
4. Guarda la clave documentada para el tipo de evento concreto y procésala de forma idempotente. Utiliza data.event_id en los tipos con clave estable, conserva los distintos intentos de subscription.payment_failed y utiliza webhook_uuid como identidad de entrega cuando esté disponible. Una entrega repetida debe producir el mismo estado final que la primera sin fusionar intentos de pago distintos.
5. Devuelve rápidamente un estado HTTP correcto y realiza después el procesamiento más largo.

Cuando una suscripción empiece, termine, se reanude o tenga un fallo de pago, utiliza la clave estable pertinente y las relaciones de suscripción y factura de la carga útil para actualizar tu vista local. Combina el tipo de evento con esas relaciones; no uses únicamente el orden de entrega como regla de negocio.

Preguntas frecuentes

¿Por qué ha llegado otra vez el mismo evento? Las entregas pueden repetirse después de un error o tiempo de espera. Deduplica mediante data.event_id cuando el tipo de evento concreto lo documente, o utiliza webhook_uuid como identidad de entrega cuando esté disponible. Conserva los distintos intentos de fallo de pago, aunque correspondan a la misma suscripción.

¿payment_failed significa lo mismo que una cancelación? No. Es un resultado de pago. Consulta por separado el estado actual de la suscripción.

¿Qué hago si el receptor no estaba disponible? Abre el registro de entregas, corrige el receptor y repite la entrega fallida cuando la integración esté lista.

Consulta la guía de API pública y webhooks (Markdown-fil, AI-agentvenlig) para conocer el flujo actual.

Elegir el evento según la necesidad de negocio

Un portal de cliente puede escuchar subscription.started para mostrar acceso, subscription.ended para cerrar un acuerdo y subscription.resumed para volver a abrirlo. Un sistema contable puede escuchar invoice.paid para marcar una cuenta por cobrar como pagada. Un sistema de soporte o pagos puede utilizar subscription.payment_succeeded y subscription.payment_failed para mostrar resultados de pago. No confundas los eventos: un pago parcial no implica necesariamente que la factura esté pagada y un fallo de pago no es por sí mismo una cancelación.

Guarda un recibo local con el tipo de evento, la clave pertinente y la hora de recepción. Ejecuta la acción de negocio solo después de verificar la firma. Si llega de nuevo el mismo event_id estable, el receptor debe devolver igualmente una respuesta correcta, pero omitir la acción ya completada. No fusiones distintas entregas de fallos de pago solo porque tengan el mismo UUID de suscripción. Si los eventos llegan en un orden inesperado, consulta el estado actual de la suscripción o la factura antes de cambiar el estado local.

¿Por qué no ha llegado ningún evento? Comprueba el endpoint, el evento seleccionado, el acceso API del equipo y el registro de entregas. Una capacidad del producto no se convierte en webhook hasta que el evento forma parte del contrato público.

¿Puede un webhook activar una acción? Sí, en tu sistema, pero haz que la acción sea idempotente e indica en qué estado de Alunta se basa.