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

Un webhook es la forma en que otro servicio le avisa a tu aplicación de que algo pasó: un pago confirmado, una devolución, un mensaje recibido. En lugar de que tu aplicación pregunte cada rato, el servicio llama a una dirección tuya cuando ocurre algo. Si quieres la diferencia con una API, la tienes en webhook y API.

Esta guía es para quien construye con un agente de código y va a montar su primer webhook. Seguimos un solo caso de principio a fin, con Stripe como ejemplo porque su documentación es de las más completas, y al final tienes el encargo listo para dárselo a Claude Code.

Imagina que esperas un paquete importante. Puedes bajar al buzón cada diez minutos a ver si llegó, o puedes esperar a que el repartidor toque el timbre. Lo primero cansa, gasta tiempo y muchas veces encuentras el buzón vacío. Lo segundo te avisa justo cuando pasa.

Un webhook es el timbre. Tu aplicación no pregunta a Stripe cada rato si alguien pagó: Stripe toca el timbre —llama a una dirección de tu servidor— en cuanto el pago se confirma. Lo que viene después es decidir qué haces tú cuando suena: comprobar quién llama, apuntarlo y abrirle la puerta al curso.

Imagina una academia en línea que vende un curso con Stripe. Cuando alguien paga, tiene que recibir acceso al curso; si se le devuelve el pago completo, el acceso se cierra. La web del curso no se entera de nada de eso por sí sola: el pago ocurre en Stripe. El webhook es el puente.

Lo que hay que decidir no es «cómo recibir un aviso», que es fácil, sino qué hace tu aplicación en cada paso para que ningún pago se quede sin acceso y ningún acceso se dé sin pago.

Un servicio como Stripe emite muchos tipos de eventos, y suscribirse a todos es la forma más rápida de llenar tu servidor de trabajo inútil. Para vender un curso con un pago único, lo esencial suele ser poco: el evento que confirma que el pago del checkout se completó, para abrir el acceso, y el que avisa de una devolución, para cerrarlo. Si vendes suscripciones, entran además los de renovación, pago fallido y cancelación.

La pregunta que conviene hacerse con cada evento es qué decisión de negocio dispara. Si no dispara ninguna, no hace falta recibirlo. Y si dispara una, esa decisión tiene que estar escrita antes de programar: qué pasa con el acceso, qué correo sale, qué se anota y quién se entera si algo falla.

Merece la pena separar dos registros. Uno, de intentos rechazados: avisos cuya firma no cuadró, con la hora y el motivo, para detectar ataques o errores de configuración. Otro, de eventos verificados: cada evento con su identificador, su tipo, el objeto al que se refiere, cuándo llegó y en qué estado está su procesamiento —pendiente, hecho o con error—.

Con esa tabla, el proceso que hace el trabajo sabe qué le queda pendiente, puede reintentar lo que falló sin volver a pedir nada al servicio y deja rastro de cada acceso que abrió o cerró. Cuando un alumno escriba diciendo que pagó y no ve el curso, la respuesta está en esa tabla: si el evento llegó, si se procesó y qué pasó.

Un webhook no es una llamada normal: llega cuando llega, puede repetirse y no respeta un orden. La documentación de Stripe lo dice expresamente, y lo mismo vale, con sus variantes, para otros servicios.

Mientras desarrollas, tu aplicación corre en tu computadora y Stripe no puede llamarla desde internet. Hay dos caminos:

• La CLI de Stripe. El comando stripe listen --forward-to localhost:4242/webhook recibe los eventos de prueba y los reenvía a tu servidor local, y te da el secreto de firma para esa sesión. No hace falta registrar ninguna dirección pública.
• Un túnel. Herramientas como ngrok dan una dirección pública que apunta a tu computadora; sirve para cualquier servicio que no tenga una herramienta propia. Con una dirección temporal, puede cambiar al reiniciar el túnel y hay que actualizarla en el servicio.

Después se disparan eventos de prueba y se comprueba el recorrido entero: que la firma se verifica, que el evento se guarda una sola vez y que el acceso se abre.

Un agente de código puede montar este webhook en poco tiempo, pero conviene revisarlo con una lista corta antes de darlo por bueno:

• La firma se comprueba con el cuerpo original. Si el código convierte el mensaje a objeto antes de verificar, la verificación puede fallar o, peor, saltarse.
• El evento se guarda antes de responder. Si responde primero y guarda después, una caída en medio pierde el aviso sin reintento.
• La unicidad está en la base de datos, no solo en el código: dos avisos iguales que llegan a la vez no deben pasar los dos.
• El secreto de firma está en las variables de entorno, nunca escrito en el código ni en el repositorio.
• Hay una prueba que repite el mismo evento y comprueba que el efecto ocurre una sola vez.

Si alguno de estos puntos falla, pídele al agente que lo corrija antes de pasar al siguiente.

Un webhook no garantiza que te enteres de todo: si tu servidor está caído más tiempo del que el servicio reintenta, el aviso se pierde. Por eso, en lo que tiene que ver con dinero, conviene una comprobación periódica que compare tus registros con los del servicio —los pagos del día en Stripe frente a los accesos abiertos—. El webhook te entera al momento; la comprobación periódica cubre los huecos.

Tampoco decide nada por ti: qué hacer con cada evento es lógica de tu negocio, y es lo que conviene escribir con detalle antes de pedírselo a un agente. Si vas a construir con Claude Code, la guía completa de Claude Code explica cómo configurarlo para trabajar así.