Webhooks en la práctica: cómo tu aplicación se entera de lo que pasa fuera

Ejemplo ilustrativo: una academia de Valladolid vende un curso mediante Stripe Checkout, la página donde el alumno completa la compra. El campus ya existe, pero necesita saber cuándo habilitar la matrícula. Un webhook es ese aviso entre aplicaciones: Stripe envía un mensaje a una dirección preparada para recibirlo. La conexión con el campus debe construirse y probarse; contratar el cobro no resuelve por sí solo la entrega del curso.

Piensa en el timbre de la academia. Suena cuando alguien llega, pero alguien debe comprobar quién es y buscar su matrícula. Con el pago ocurre algo parecido: el aviso inicia un trabajo. No demuestra que ese trabajo haya terminado. Para seguir el recorrido no necesitas programar, sino saber qué resultado pedir y cómo revisarlo. Consulta qué es un webhook para repasar la definición antes de seguir esta compra hasta el acceso.

En la receta de Checkout, checkout.session.completed informa de la finalización de Checkout. Para métodos diferidos aparecen checkout.session.async_payment_succeeded y checkout.session.async_payment_failed. El nombre del aviso no sustituye consultar el estado del pago. Para devoluciones, charge.refunded incluye las parciales; Stripe recomienda escuchar al menos refund.created y contempla actualizaciones y fallos. Pide a tu proveedor que explique cuáles usa y qué regla aplica con cada uno.

Hay dos formatos de aviso que conviene fijar antes de construir: thin, con información ligera, y snapshot, con una copia de los datos de ese momento. Stripe recomienda thin para nuevas integraciones, mientras que su guía de entrega de compras con Checkout muestra snapshot. Quien programe debe elegir un catálogo de eventos y una biblioteca de programación compatibles; la biblioteca aporta las funciones para conectar la aplicación con Stripe. Mezclar ejemplos de ambos puede llevar a interpretar mal el contenido o a comprobarlo con una función que no corresponde.

Stripe no asegura el orden de entrega de los eventos. Si necesitas conocer la situación actual, consúltala mediante su API, la conexión que permite a tu programa pedir datos a Stripe. La fecha del aviso no basta para decidir el orden de todo el proceso. En una incidencia, pide que se identifique la compra y se contraste su estado antes de aplicar cambios sobre información incompleta.

Prepara la aplicación para recuperar lo pendiente y comparar pagos con matrículas. Asigna un responsable que pueda localizar una compra cobrada, ver dónde se detuvo y comprobar el resultado tras recuperarla. Esta revisión del negocio complementa al receptor. Si el panel indica que Stripe entregó el mensaje, aún queda comprobar qué hizo el campus. No cierres la incidencia hasta que el acceso y su registro coincidan con la regla aprobada.

Con poco volumen puedes revisar pagos y dar acceso a mano; Stripe contempla la entrega manual. Automatizar tiene sentido si necesitas que el proceso continúe sin esa intervención. Antes de elegir, acuerda quién comprobará las matrículas, quién atenderá una incidencia y qué mantenimiento está incluido. La cuota de una herramienta no describe todo el trabajo necesario para conectar tu campus.

Si eliges n8n, un nodo es una pieza del flujo que recibe datos o realiza una acción. El nodo Webhook distingue dirección de prueba y de producción; esta última se registra al publicar el flujo. Que funcione mientras haces la prueba no demuestra que el recorrido publicado esté preparado. Pide verificar su dirección, su configuración y la matrícula final. Tener un editor visual no elimina las comprobaciones de un cobro.

Stripe ofrece una CLI, una herramienta que usas escribiendo órdenes en la terminal. Puede reenviar avisos a tu ordenador mientras desarrollas. La orden de abajo ilustra esa escucha local, con el puerto y la ruta que muestra la documentación; quien la use debe adaptarlos a la aplicación. Para este recorrido básico no necesitas añadir un túnel comercial. Ensayar aquí y poner el receptor en internet son comprobaciones separadas.

La escucha local proporciona su propio secreto de firma, distinto del que aparece para el receptor del panel. Guarda cada secreto en la configuración privada del servidor que corresponda. No lo pegues en el encargo, en archivos publicados ni en una demostración. Si falla la firma al probar, comprueba primero el cuerpo original y qué secreto estás utilizando. No cambies a modo real para intentar resolver un fallo de configuración de las pruebas.

La orden stripe trigger genera objetos de prueba y puede producir varios eventos relacionados. Ejecutarla otra vez crea otra simulación, no demuestra que hayas reenviado el mismo aviso. Para probar la repetición, utiliza el reenvío de un evento existente. Pide que el proveedor muestre el identificador usado, el resultado de ambos intentos y la matrícula que queda al terminar. Así puedes revisar qué se ensayó sin tener que interpretar todo el código.

El calendario de pruebas de Stripe tampoco es el de producción: en pruebas hace tres reintentos durante unas horas. Las ventanas anteriores pertenecen a Stripe, no a todos los webhooks. GitHub, por ejemplo, no reenvía automáticamente las entregas fallidas. Si después conectas otro servicio, vuelve a preguntar qué conserva, cómo reintenta y cómo se recupera. No traslades una regla de esta integración a cualquier aviso que llegue desde fuera.

Claude Code es un agente de código: ayuda a leer el proyecto, cambiar archivos y ejecutar comprobaciones. El receptor publicado debe continuar como software de tu negocio; no necesita que una IA interprete cada aviso. Pide una entrega que puedas revisar: qué conexión se ha instalado, qué reglas aplica, dónde ves su resultado y a quién llamas si una matrícula queda pendiente. Para distinguir ambas tareas, consulta qué es un agente de código.

Los permisos se configuran. Las aprobaciones para publicar, mover dinero o cambiar accesos sensibles deben estar en las herramientas y en el proceso de trabajo; no basta con una frase en el encargo. La guía completa de Claude Code te ayuda a situar ese trabajo. Si quieres seguir ese recorrido, tienes el curso Claude Code a fondo y su ebook.