¿Qué es un webhook? Cómo las apps se avisan 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, desbloquea 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 construyes con IA

En cuanto tu app cobra pagos, recibe envíos de 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 ocurrido, pero también es donde las apps construidas con IA suelen fallar de forma sutil:

• El endpoint acepta cualquier petición, así que cualquiera puede simular 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 quienes cierran la pestaña pronto no reciben lo que pagaron, y quienes encuentran la URL de éxito lo obtienen 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 las protecciones desde el principio.

Una analogía cotidiana: un mensaje de entrega

Puedes saber si tu paquete ha llegado de dos formas. Puedes ir a la puerta cada diez minutos a comprobarlo (eso es polling: tu app llama repetidamente a una API para preguntar «¿hay algo nuevo?»). O el mensajero puede enviarte 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 venía del mensajero. Y si tu teléfono estaba apagado cuando llegó el SMS, querrías que el mensajero lo intentara de nuevo más tarde. Esas dos preocupaciones —verificación y reintentos— son la mayor parte de lo que hace que los webhooks sean complicados.

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 de checkout 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, junto con una cabecera de firma.
5. Tu app verifica la firma, registra el ID del evento, responde rápidamente con un código de éxito (200) y luego hace el trabajo.
6. Si tu app no responde con éxito, muchos proveedores lo vuelven a intentar 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 la 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 haya grabado y reproduzca 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 (raw) de la petición. Si tu framework analiza y vuelve a formatear el JSON antes de verificarlo, la comprobación falla. Es un error muy común.

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 indica que los eventos no tienen garantizado llegar 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 produce el mismo efecto que procesarlo una vez.

Un ejemplo práctico: desbloquear un curso de pago

Vendes un curso en línea. Un estudiante pulsa Comprar, paga en la página de checkout alojada por Stripe y vuelve a tu sitio.

La forma frágil: la página de «gracias» desbloquea el curso. Si el estudiante cierra el navegador durante la redirección, ha pagado pero no tiene acceso. Si alguien adivina la URL de la página de gracias, obtiene 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 estudiante 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 estudiante.

Más tarde, si una suscripción se cancela 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 ocurrió, 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 si hay 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 PDFs antes de responder puede causar tiempos de espera, que provocan reintentos, que causan duplicados.
• Asumir que llega exactamente una vez y en orden. Registra los ID de evento y no confíes en el orden de llegada.
• Usar una URL de vista previa. Los webhooks necesitan una dirección pública y estable. Las vistas previas 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 los modos de prueba y real. Guarda ambos y usa el correcto.
• Confiar ciegamente en el payload para decisiones importantes. Para acciones de alto riesgo, es razonable consultar el estado más reciente en 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 de la petición sin procesar y el secreto STRIPE_WEBHOOK_SECRET. Rechaza las firmas inválidas con 400. Guarda cada ID de evento y omite los eventos ya procesados. Responde 200 rápidamente y luego 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 checkout.

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 ejecuta un servicio de webhooks aparte; pides al agente que añada un endpoint de webhook en el propio backend de tu 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 de inicio, y las plantillas de tiendas son un buen punto de partida para apps que cobran pagos.

Preguntas