Túneles programáticos para pipelines CI/CD: automatización de URLs efímeras para pruebas de Webhook

Durante años, los túneles locales fueron exclusivamente dominio de desarrolladores individuales que ejecutaban binarios CLI en sus laptops. Si necesitabas probar un pago con Stripe o un evento de GitHub, abrías una terminal, ejecutabas un comando, copiabas la URL y la pegabas manualmente en un panel. En 2026, ese flujo de trabajo aún existe — pero los equipos avanzados de QA y plataformas cada vez lo saltan más. En lugar de ejecutar un binario CLI a mano, generan URLs públicas efímeras programáticamente, directamente desde un suite de pruebas o un trabajo de CI/CD. Al importar una librería de tunneling directamente en código Node.js, los equipos de ingeniería obtienen pruebas de endpoints totalmente automatizadas y validación real de webhook de extremo a extremo, sin que ningún humano toque una terminal.

El cambio de CLI a código

Las herramientas de tunneling por línea de comandos son fantásticas para desarrollo local. Herramientas como ngrok, Pinggy y Cloudflare Tunnel perfeccionaron la experiencia de compartir un puerto localhost con un solo comando. Pero los CLIs introducen fricción en la automatización. Si un pipeline de CI/CD necesita verificar que tu aplicación procesa correctamente un webhook entrante, un binario independiente es torpe: tienes que lanzarlo como proceso en segundo plano, extraer su stdout para obtener una URL generada dinámicamente, y gestionar cuidadosamente su ciclo de vida para que no queden procesos huérfanos en el runner.

Un túnel programático resuelve esto de forma limpia. En lugar de invocar un binario externo, importas una librería directamente en tu suite de pruebas o código de aplicación. El túnel se vuelve simplemente otra llamada asíncrona que resuelve en una URL pública, lista para entregarle a un navegador sin cabeza o a una API de terceros.

La historia de npm’s localtunnel, y hacia dónde van los desarrolladores

Históricamente, los desarrolladores de Node.js recurrían al paquete npm localtunnel para resolver esto. Era realmente útil porque permitía exponer un puerto en unas pocas líneas de JavaScript:

const localtunnel = require('localtunnel');

(async () => {
  const tunnel = await localtunnel({ port: 3000 });

  // por ejemplo https://abcdefgjhij.loca.lt
  console.log(tunnel.url);

  tunnel.on('close', () => {
    // el túnel se cierra
  });
})();

El proyecto aún está en npm y sigue funcionando, pero su historia en GitHub cuenta su propia historia: el repositorio original pasó largos periodos con poca actividad de mantenedores, y la comunidad respondió creando más de una docena de forks independientes y paquetes envolventes (tunnelout, varias imágenes Dockerizadas de localtunnel-server, puertos en diferentes lenguajes, etc.) para mantener vivo el ecosistema. Ese patrón — muchos forks, atención inconsistente del upstream — suele ser señal de que un equipo no debería construir infraestructura CI sobre el servicio gratuito loca.lt sin un plan de respaldo. Para 2026, la mayoría de los equipos que construyen túneles programáticos para pipelines de prueba han migrado a alternativas más nuevas y activamente mantenidas.

Aquí una mirada honesta a dónde han llegado, con código corregido y verificado para cada uno:

Tunnelmole

Tunnelmole es una herramienta de tunneling completamente de código abierto — el cliente tiene licencia MIT y el servicio de respaldo es AGPLv3 — lo que significa que ambos componentes pueden ser auditados o auto-hospedados si no quieres depender de la disponibilidad de un tercero. Está escrito nativamente en TypeScript para el ecosistema Node.js, en lugar de envolver un binario externo.

La API programática real (esto corrige una función serve() inventada que circuló en un borrador anterior) es una sola función, exportada como módulo ES y CommonJS:

// ESM
import { tunnelmole } from 'tunnelmole';

// o CommonJS
// const tunnelmole = require('tunnelmole/cjs');

const url = await tunnelmole({ port: 3000 });
// url = https://idsq6j-ip-157-211-195-169.tunnelmole.net

La función es async y devuelve directamente la URL pública asignada, por lo que puede integrarse en un hook beforeAll. Dos detalles importantes para CI específicamente:

• Tunnelmole recopila telemetría anónima (versión de Node, SO, informes de fallos) por defecto. Configura TUNNELMOLE_TELEMETRY=0 en el entorno para desactivarla en un runner.
• Configura TUNNELMOLE_QUIET_MODE=1 para suprimir la banner de consola que normalmente imprime, manteniendo los logs de CI más limpios.
• Los subdominios personalizados y estables requieren un plan de pago en el servicio hospedado o una instancia auto-hospedada — la capa gratuita siempre devuelve un subdominio aleatorio, que suele ser suficiente para ejecuciones efímeras de prueba.

SDK oficial de Node.js de ngrok

El borrador original de este artículo decía que el SDK de ngrok “envuelve su binario Go de código cerrado,” lo cual era cierto de una versión antigua y no oficial del paquete npm ngrok (el que descarga y lanza el ejecutable ngrok como proceso hijo) — pero no es cómo funciona el SDK oficial actual de ngrok. @ngrok/ngrok es descrito por ngrok como que no requiere binarios; es un enlace nativo en Node.js construido sobre las librerías Rust de ngrok, no un envoltorio de child_process.

const ngrok = require("@ngrok/ngrok");

(async function () {
  const listener = await ngrok.forward({
    addr: 8080,
    authtoken_from_env: true, // lee NGROK_AUTHTOKEN
  });

  console.log(`Ingress establecido en: ${listener.url()}`);
})();

Aún necesitas un authtoken de una cuenta gratuita de ngrok para la mayoría de funciones (dominios personalizados, sesiones de mayor duración, etc.), configurado como NGROK_AUTHTOKEN en tus secretos de CI. Pero la crítica de “envuelve un binario” aplica al paquete comunitario legado, no a los SDK que en realidad deberías usar en 2026.

Pinggy: SSH es la API, no un SDK especial

Pinggy no ofrece un SDK dedicado en Node.js como ngrok o LocalXpose. Lo que ofrece es:

1. Un CLI oficial y activo (npm install -g pinggy, requiere Node.js 18+), que imprime la URL generada pinggy.link en stdout y puede ser lanzado como proceso hijo desde un script de prueba, o
2. Nada más exótico que el reenvío de puertos SSH remoto, que puedes automatizar directamente con una librería como ssh2 en lugar de invocar el binario ssh: ssh -p 443 -R0:localhost:3000 a.pinggy.io

Ese comando (o su equivalente con ssh2) es toda la “API” — Pinggy devuelve una URL pública https://<aleatorio>.pinggy.link una vez establecido el túnel inverso. Dos notas prácticas para CI: la capa gratuita limita la sesión a aproximadamente 60 minutos, suficiente para pruebas de webhook, pero importante saberlo si un stage de pipeline dura mucho; y enrutar por puerto 443 (en lugar de 22) es útil en runners que solo permiten tráfico HTTPS saliente.

LocalXpose

El borrador anterior subestimó a LocalXpose, describiendo su “soporte de librería programática” como que requiere “integraciones específicas.” En realidad, LocalXpose ofrece un enlace oficial, limpio, basado en promesas, en Node.js, que soporta túneles HTTP, TLS, TCP y UDP desde el mismo objeto cliente:

const LocalXpose = require('localxpose');

// Funciona como invitado con limitaciones, o pasa un token de acceso
// (o configura LOCALXPOSE_ACCESS_TOKEN en el entorno)
const client = new LocalXpose();

(async function () {
  const httpTunnel = await client.http({
    to: '127.0.0.1:3000',
    region: 'us', // us, ap, eu
  });

  console.log(`Disponible en ${httpTunnel.addr}`);
})();

Dado que LocalXpose es una de las pocas herramientas en este espacio con soporte de túneles UDP de primera clase, vale la pena considerarla si tu pipeline necesita probar algo más allá de webhooks HTTP — servidores de juegos, simuladores de dispositivos IoT u otras integraciones UDP.

Los riesgos ocultos de webhooks sin control

¿Por qué hacer el esfuerzo de un túnel programático en un entorno CI? Porque los webhooks fallan en silencio, y los fallos silenciosos son los más caros.

El software moderno depende mucho de integraciones basadas en eventos. Los equipos escriben pruebas unitarias exhaustivas para sus APIs internas, pero rara vez automatizan pruebas para cómo su aplicación maneja eventos de un proveedor externo. Cuando Stripe cambia un formato de timestamp o GitHub rota un esquema de firma, las pruebas unitarias con payloads mock estáticos siguen pasando. La build se marca como exitosa. La integración se rompe en producción.

Probar automáticamente un endpoint a través de un túnel real obliga a tu aplicación a recibir una solicitud HTTP POST auténtica — con encabezados reales y firma criptográfica real — y procesarla correctamente, antes de que el código se fusione a la rama principal.

Cómo construir un túnel programático en Node.js

Así se ve en un suite de pruebas con Jest o Mocha, usando la API corregida de Tunnelmole como ejemplo:

import { tunnelmole } from 'tunnelmole';
import app from '../src/app.js';
import http from 'http';

let server;
let publicUrl;

beforeAll(async () => {
  // 1. Iniciar el servidor local en un puerto dinámico
  server = http.createServer(app);
  server.listen(3000);

  // 2. Establecer el túnel programáticamente
  publicUrl = await tunnelmole({ port: 3000 });

  console.log(`Entorno de prueba expuesto en: ${publicUrl}`);
});

afterAll(() => {
  // 3. Limpiar
  server.close();
  // Tunnelmole no requiere una llamada explícita de cierre para el servicio hospedado,
  // pero siempre cierra tu servidor HTTP local para que el proceso pueda salir limpio.
});

Porque publicUrl es solo una variable en tu ámbito de prueba, puedes pasársela a una instancia sin cabeza de Playwright o entregarla a una API de terceros (Shopify, Slack, Stripe) y decirle que entregue eventos de prueba allí.

Pruebas de Webhook en GitHub Actions

El objetivo final del tunneling programático es una integración completa en CI/CD: aislar la aplicación en un runner controlado, levantar el servidor HTTP, tunelizarlo a internet y simular un webhook real de un tercero. Un pipeline típico divide esto en cuatro fases:

Fase 1 — Provisionamiento del entorno. El workflow inicia la aplicación objetivo junto con los servicios de respaldo necesarios (Postgres, Redis) usando soporte de contenedores nativo de GitHub.

Fase 2 — Túnel programático. Un script en Node.js lanza el servidor y abre un túnel con alguna de las librerías mencionadas, capturando la URL HTTPS resultante como variable o salida de entorno.

Fase 3 — Inyección de payload. El script dispara un evento webhook real. Para Stripe, esto implica ejecutar dos comandos separados del CLI de Stripe, no uno solo — un detalle importante, ya que stripe trigger y stripe listen hacen trabajos diferentes:

# 1. En segundo plano, reenviar eventos de Stripe a la URL del túnel y
#    capturar el secreto de firma del webhook que imprime
stripe listen --forward-to "$EPHEMERAL_URL/webhooks/stripe" &

# 2. Por separado, pedir a Stripe que genere un evento de prueba
stripe trigger payment_intent.succeeded

--forward-to es una bandera en stripe listen, que suscribe a eventos en modo prueba en vivo y los reenvía a un endpoint local o tunelizado. stripe trigger es un comando diferente que llama a la API de Stripe para crear el objeto que dispara el evento — no acepta --forward-to. Ejecutar listen en segundo plano primero, y luego disparar trigger una vez conectado, es el patrón que Stripe describe en su documentación.

Fase 4 — Verificación del estado. La suite de pruebas espera a que la aplicación reciba el webhook, verifica que devuelve 200 OK (para que Stripe no reintente), y comprueba el cambio de estado en la base de datos de pruebas — por ejemplo, que una suscripción cambió a active.

Ejemplo de flujo en GitHub Actions

name: Prueba de integración de Webhooks
on:
  pull_request:
    branches: [ main ]

jobs:
  test-webhooks:
    runs-on: ubuntu-latest

    steps:
      - name: Clonar código
        uses: actions/checkout@v6

      - name: Configurar Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22'

      - name: Instalar dependencias
        run: npm ci

      - name: Instalar CLI de Stripe
        run: |
          curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg
          echo "deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main" | sudo tee -a /etc/apt/sources.list.d/stripe.list
          sudo apt-get update && sudo apt-get install stripe

      - name: Ejecutar túnel y pruebas programáticas
        env:
          STRIPE_API_KEY: ${{ secrets.STRIPE_TEST_KEY }}
        run: npm run test:webhooks

Dos actualizaciones respecto al flujo original: actions/checkout y actions/setup-node ahora en versión mayor 6 (ambas v4 y v5 están desactualizadas), y la versión de Node.js en el entorno cambió de 20 a 22 — Node.js 20 alcanzó fin de vida en abril de 2026, por lo que fijar CI a esa versión implica usar un entorno sin parches de seguridad. Node 22 está en soporte activo/maintenance hasta abril de 2027; Node 24 sería la opción más moderna y en soporte activo si quieres más margen.

Dentro de npm run test:webhooks, tu código en JavaScript coordina todo: abrir el túnel, iniciar stripe listen en segundo plano, llamar a stripe trigger vía child_process, y hacer las aserciones.

Mejores prácticas y seguridad en túneles CI

Exponer un runner de CI a internet público, aunque sea efímeramente, requiere gobernanza real:

Ephemeridad estricta. Nunca dejes un túnel corriendo más tiempo del necesario. Usa try/finally o hooks afterAll para cerrar agresivamente tanto el túnel como el servidor local, incluso si falla la prueba. Un job de CI colgado puede consumir límites de concurrencia y costar dinero.

Ocultar salidas sensibles. Si la URL del túnel o la salida del proveedor contienen información sensible, elimínala de los logs de CI. GitHub Actions soporta esto nativamente con el comando ::add-mask:::

echo "::add-mask::$EPHEMERAL_URL"

Todo lo registrado así será tratado como secreto y eliminado del log en lo que reste de la ejecución — pero debes registrarlo con add-mask antes de que se imprima en cualquier parte, ya que el masking solo aplica hacia adelante. La misma función de masking está disponible programáticamente con core.setSecret() en el paquete @actions/core si tu setup de túnel es una Acción JavaScript personalizada.

Verifica el análisis del cuerpo crudo. La causa más común de errores “Webhook válido rechazado” en producción es middleware que muta el cuerpo HTTP en crudo antes de verificar la firma. Como un túnel real enruta tráfico HTTP genuino a tu stack de servidores, valida que el análisis de firma HMAC-SHA256 (el esquema que usan Stripe y GitHub para sus firmas) funciona exactamente igual que en producción — algo que un payload mock estático nunca puede detectar.

Maneja concurrencia y colisiones de puertos. Los runners de CI ejecutan trabajos en paralelo frecuentemente. Configura tu servidor Node.js para listen(0) para que el SO asigne un puerto aleatorio, y pasa ese puerto a la configuración del túnel. Esto evita conflictos cuando varias solicitudes de extracción se prueban simultáneamente en infraestructura compartida.

Conoce los límites de sesión de cada herramienta. Las capas gratuitas en servicios de túneles hospedados suelen limitar la duración de la sesión — Pinggy, por ejemplo, limita a unos 60 minutos. Esto rara vez es problema para pruebas de webhook que duran segundos o minutos, pero vale verificar contra la etapa más lenta de tu pipeline antes de confiar en una capa gratuita en CI.

Conclusión

La era de verificar webhooks manualmente pegando URLs en dashboards terminó para equipos con CI/CD serio. Al pasar de un binario CLI independiente a un túnel programático en un suite de pruebas Node.js, la entrada de red se vuelve simplemente otro código testeable. Cualquiera que sea la librería que elijas — Tunnelmole por ser open-source y auto-hospedable; el SDK nativo de ngrok por su madurez y herramientas de dashboard; Pinggy por su simplicidad SSH; o LocalXpose por soporte UDP y multi-protocolo — el pipeline resultante es el mismo: las integraciones externas se prueban contra tráfico HTTP real, con firmas reales, mucho antes de que un cliente haga clic en “Pagar.”

---

Cambios en el contenido

Este artículo fue reescrito desde un borrador anterior usando el flujo de trabajo de verificación de hechos estándar del blog: cada afirmación técnica fue revisada contra la documentación oficial o repositorio fuente de cada proyecto antes de publicar. Cambios respecto al borrador original:

1. Se eliminaron artefactos de metadatos/formato del archivo fuente y se reestructuró en Markdown limpio, con encabezados reales y bloques de código con fences (el original tenía párrafos largos por exportación de documento fuente).
2. Se corrigió el ejemplo de código de Tunnelmole. El original inventó una función serve() que no existe en el paquete. La API real y actual es tunnelmole() (o require('tunnelmole/cjs') para CommonJS), una función async que resuelve en la URL pública directamente. Se añadió la división de licencias (MIT cliente / AGPLv3 servicio), el comportamiento predeterminado de telemetría, y las variables de entorno TUNNELMOLE_QUIET_MODE / TUNNELMOLE_TELEMETRY relevantes para CI, que no estaban en el original.
3. Se corrigió la caracterización del SDK de ngrok. El original afirmó que envuelve su binario Go cerrado. Eso es cierto de un paquete comunitario ngrok no oficial, pero el SDK oficial actual (@ngrok/ngrok) requiere ningún binario externo; es un enlace nativo en Node.js construido sobre las librerías Rust de ngrok, no un envoltorio de proceso hijo. La explicación ahora distingue ambos y proporciona un ejemplo verificado.
4. Se corrigió la historia del soporte programático de LocalXpose. El original describió vagamente que requiere “integraciones específicas.” En realidad, LocalXpose publica un enlace oficial, limpio, basado en promesas, en Node.js, que soporta túneles HTTP, TLS, TCP y UDP desde un solo objeto cliente — una de las opciones más sencillas en este espacio, no una integración a medida.
5. Se aclaró la superficie programática real de Pinggy. No existe un SDK dedicado en Node.js; las opciones reales son el CLI oficial (que puede lanzarse como subprocesso) o el reenvío SSH manual vía librerías como ssh2. Se añadió la limitación de sesión gratuita de unos 60 minutos, relevante en CI, que la original omitió.
6. Se corrigió el ejemplo de CLI de Stripe. La original combinó stripe trigger con la bandera --forward-to como si fuera un solo comando. --forward-to pertenece a stripe listen, no a stripe trigger — son comandos separados con funciones distintas. Se reemplazó por el patrón correcto: ejecutar listen en segundo plano, luego llamar a trigger por separado, según la documentación.
7. Se actualizó el flujo de GitHub Actions. Se subieron actions/checkout y actions/setup-node de v4 a v6, la versión mayor actual (agosto 2026), y la versión de Node.js cambió de 20 a 22, que está en soporte activo hasta abril de 2027. Node 20 finalizó en abril de 2026.
8. Se suavizó una afirmación de fiabilidad. La original afirmó que npm localtunnel sufre “problemas de uptime y abuso” sin soporte. Se reemplazó por una observación documentada: el repositorio tiene historia de largos periodos sin mantenimiento, evidenciado por más de una docena de forks comunitarios, lo cual es una señal razonable para evaluar su uso.
9. Se verificó y dejó sin cambios: el comando ::add-mask:: en GitHub Actions (incluyendo que puede activarse programáticamente con core.setSecret()), y la afirmación general de que HMAC-SHA256 es el esquema de firma usado por Stripe y GitHub webhooks.