¿Qué es un webhook? Cómo se avisan las apps entre sí

Un webhook es un mensaje automático que un servicio envía a tu app en el momento en que ocurre algo. Cuando el pago de un cliente se completa, Stripe envía un webhook a una dirección de tu app que dice «pago completado, aquí están los detalles», y tu app reacciona: marca el pedido como pagado, envía el recibo, activa la cuenta. En resumen: una API es tu app preguntando algo a otro servicio; un webhook es el otro servicio llamando a tu app para decirle algo.

Por qué importa cuando creas con IA

En cuanto tu app cobra pagos, recibe formularios de otra herramienta o se conecta a servicios como GitHub, Shopify o un calendario, te encontrarás con webhooks. Suelen ser la forma correcta de saber que algo ha pasado, pero también es donde las apps creadas con IA suelen fallar de forma sutil:

• El endpoint acepta cualquier petición, así que cualquiera puede falsificar un evento de «pago completado».
• La app concede acceso en la página de redirección del pago en lugar de hacerlo en el webhook, así que quien cierra la pestaña antes no recibe lo que pagó, y quien encuentra la URL de éxito lo obtiene gratis.
• El mismo evento llega dos veces y el cliente recibe dos pedidos o dos correos.

Saber cómo funcionan los webhooks te permite pedir estas protecciones desde el principio.

Una analogía cotidiana: el SMS de la entrega

Puedes saber si tu paquete ha llegado de dos maneras. Puedes ir a la puerta cada diez minutos a comprobarlo (eso es polling — tu app llamando una y otra vez a una API para preguntar «¿hay algo nuevo?»). O el mensajero puede mandarte un SMS cuando lo entregue (eso es un webhook).

El SMS es claramente mejor — siempre que puedas confiar en él. Si cualquiera pudiera enviarte un mensaje de «paquete entregado», querrías alguna forma de saber que realmente llegó del mensajero. Y si tu teléfono estaba apagado cuando llegó el mensaje, querrías que el mensajero lo intentara de nuevo más tarde. Esas dos cuestiones — verificación y reintentos — son casi todo lo que hace que los webhooks sean delicados.

Cómo funciona un webhook, paso a paso

1. Creas un endpoint en el backend de tu app: una URL como https://tuapp.com/webhooks/stripe que acepta peticiones POST.
2. Registras esa URL en el proveedor y eliges qué eventos quieres (por ejemplo, «pago completado» y «suscripción cancelada»).
3. El proveedor te da un secreto de firma. Lo guardas como secreto en tu servidor — consulta variables de entorno y secretos.
4. Ocurre un evento. El proveedor envía una petición HTTP a tu URL con un cuerpo JSON que describe el evento, más una cabecera de firma.
5. Tu app verifica la firma, registra el ID del evento, responde rápido con un código de éxito (200) y después hace el trabajo.
6. Si tu app no responde con éxito, muchos proveedores vuelven a intentarlo más tarde.

Firmas

Una firma demuestra que la petición viene del proveedor y que no ha sido alterada. Stripe, por ejemplo, calcula un HMAC (una especie de huella digital con clave) con SHA-256 sobre el cuerpo de la petición y una marca de tiempo, usando el secreto de firma, y lo envía en una cabecera Stripe-Signature. Tu app hace el mismo cálculo con su copia del secreto; si los resultados coinciden, la petición es auténtica. Como la marca de tiempo también está firmada, puedes rechazar peticiones antiguas que alguien grabó y reenvía más tarde — las librerías de Stripe usan por defecto una tolerancia de cinco minutos, según su documentación a septiembre de 2026.

Un detalle práctico: la firma se calcula sobre el cuerpo sin procesar de la petición. Si tu framework parsea y vuelve a formatear el JSON antes de verificar, la comprobación falla. Es un error muy habitual.

Reintentos, duplicados y orden

Los proveedores difieren, así que consulta la documentación de cada uno. A septiembre de 2026:

La documentación de Stripe también dice que no se garantiza que los eventos lleguen en el orden en que ocurrieron, y que el mismo evento puede llegar más de una vez de forma ocasional, así que recomienda registrar los ID de evento.

La lección general vale para cualquier proveedor: los eventos pueden llegar tarde, más de una vez y desordenados. Tu manejador debe ser idempotente — procesar el mismo evento dos veces tiene el mismo efecto que procesarlo una vez.

Un ejemplo práctico: desbloquear un curso de pago

Vendes un curso online. Un alumno pulsa Comprar, paga en la página de pago alojada de Stripe y vuelve a tu web.

La forma frágil: la página de «gracias» desbloquea el curso. Si el alumno cierra el navegador durante la redirección, ha pagado pero no tiene acceso. Si alguien adivina la URL de la página de gracias, tiene acceso sin pagar.

La forma con webhook:

1. Cuando Stripe confirma el pago, envía un evento checkout.session.completed a /webhooks/stripe.
2. Tu backend verifica la firma con el secreto de firma. Si falla, responde 400 y no hace nada.
3. Comprueba si ese ID de evento ya se procesó. Si es así, responde 200 y se detiene.
4. Guarda el ID del evento, responde 200 y después concede acceso al alumno y envía un correo de bienvenida.
5. La página de gracias solo dice «Pago recibido — tu curso aparecerá en un momento» y consulta el estado de acceso del alumno.

Más adelante, si se cancela una suscripción o falla una tarjeta, otros eventos de webhook indican a tu app que retire o pause el acceso. Así es como los productos de suscripción se mantienen sincronizados con la facturación: consulta qué es SaaS y cómo añadir pagos a tu app.

Términos clave

• Endpoint: la URL de tu app que recibe los webhooks.
• Evento / payload: lo que ha pasado, y los datos que lo describen (normalmente JSON).
• Secreto de firma: el secreto compartido que se usa para verificar las firmas.
• Idempotente: seguro de ejecutar más de una vez con el mismo resultado.
• Polling: preguntar repetidamente a una API por cambios en lugar de esperar un webhook.
• Túnel: una herramienta que da a un portátil una URL pública temporal para que los webhooks lleguen durante el desarrollo.

Errores comunes e ideas equivocadas

• No verificar las firmas. La URL del endpoint no es un secreto. La verificación es lo que hace fiable la petición.
• Hacer trabajo lento antes de responder. Enviar correos o generar PDF antes de contestar puede provocar tiempos de espera, que provocan reintentos, que provocan duplicados.
• Asumir que llega exactamente una vez y en orden. Registra los ID de evento y no te fíes del orden de llegada.
• Usar una URL de vista previa. Los webhooks necesitan una dirección pública y estable. Las vistas privadas y localhost no son accesibles desde internet; usa tu URL publicada (o un túnel mientras pruebas).
• Mezclar secretos de prueba y reales. Los proveedores suelen emitir secretos de firma distintos para el modo de prueba y el modo real. Guarda ambos y usa el correcto.
• Confiar ciegamente en el payload para decisiones importantes. Para acciones de alto riesgo, es razonable obtener el estado más reciente desde la API del proveedor después de recibir el evento.

Qué pedir a tu constructor de IA

Añade un endpoint POST /webhooks/stripe en el servidor. Verifica la firma de Stripe usando el cuerpo sin procesar de la petición y el secreto STRIPE_WEBHOOK_SECRET. Rechaza las firmas no válidas con 400. Guarda el ID de cada evento y omite los eventos ya procesados. Responde 200 rápido y después gestiona checkout.session.completed marcando el pedido como pagado y enviando el recibo. Registra el tipo de evento. No concedas acceso desde la página de éxito del pago.

Después pruébalo: envía un evento de prueba desde el panel del proveedor, envía el mismo otra vez y envía una petición con una firma incorrecta. Solo el primero debería cambiar algo.

Webhooks en Mythex

Mythex no tiene un servicio de webhooks aparte; pides al agente que añada un endpoint de webhook en el backend de tu propia app, y configuras el proveedor para que apunte a tu URL publicada, ya que los webhooks necesitan una dirección pública. El secreto de firma va a los secretos de tu proyecto, y si lo cambias en una app en vivo, vuelves a publicar. La receta de la documentación sobre gestionar webhooks tiene un prompt inicial, y las plantillas de tiendas son un buen punto de partida para apps que cobran pagos.

Preguntas