InstaTunnel
Abrir menu de navegacion
API
15 min read
66 views

¿Cierre de Webhook v1? Prueba la migración v1 → v2 lado a lado en localhost

¿Webhook v1 en desuso? Ejecuta v1 y v2 lado a lado en localhost con subdominios estables, difiere las cargas útiles y sigue una lista de verificación de transición segura.

IT
InstaTunnel Team
Published by the InstaTunnel team | Editorial policy
¿Cierre de Webhook v1? Prueba la migración v1 → v2 lado a lado en localhost

Quick answer

Webhook v1 Shutdown? Test v1 to v2 Migration on Localhost: quick answer

If free tunnel limits interrupt your workflow, compare session length, stable URLs, concurrent tunnels, and paid-plan pricing before choosing a localhost tunnel tool.

What free tunnel limits should developers check first?

Check session duration, URL stability, concurrent tunnels, custom subdomains, bandwidth or request limits, and whether webhook callbacks survive restarts.

How does InstaTunnel handle longer development sessions?

InstaTunnel Free is designed around 24-hour sessions, with Pro available for higher limits and MCP endpoint tunnel workflows.

Penneo’s legacy webhook service is fully decommissioned on November 30, 2026, which is 14 days from November 16, 2026. After that date, any integration still subscribed through v1 stops receiving events. Qlik is retiring its legacy webhook payload fields on a separate schedule and moving its webhook management API to a new path. GitLab’s own January 2026 planning issue says it has no webhook versioning strategy, so deprecated fields have no removal timeline.

Estos son tres proveedores con tres modos de fallo diferentes, y una única respuesta segura. Ejecute en paralelo las rutas antiguas y nuevas de webhook contra URLs estables en su propia máquina, capture lo que cada una envía realmente, compare los resultados y solo entonces haga el corte. Esta guía usa dos subdominios de túnel, dos receptores pequeños, un script de diff de cargas útiles, un verificador de firmas y una checklist de transición.

Tres deprecaciones de Webhook, tres relojes diferentes

Proveedor Cambios Fecha
Penneo Servicio webhook heredado (v1) desmantelado; los eventos dejan de llegar 30 de noviembre de 2026
Qlik Cloud Campos heredados eliminados de las cargas útiles de webhook (híbrido → CloudEvents únicamente) 10 de diciembre de 2026 (trasladado desde 6 de octubre)
Qlik Cloud Eventos de identidad y gestión de acceso heredados reemplazados por com.qlik.core.* En o después del 30 de noviembre de 2026
Qlik Cloud API de gestión /api/v1/webhooks eliminada En o después del 1 de noviembre de 2027
GitLab Sin versionado de webhook ni cronograma de eliminación (según la incidencia #588235 de GitLab) Abierta

Penneo anunció la deprecación el 21 de mayo de 2026. Su panorama de depreciación lista el servicio heredado como “Deprecated”, que Penneo define como que aún funciona pero recibe correcciones críticas y de seguridad solamente. La guía de migración dice que si no has migrado, ya no recibirás actualizaciones de eventos después del 30 de noviembre. No menciona un periodo de gracia.

Qlik tiene la historia más estratificada, y los tres cambios son fáciles de confundir:

  • Ruta de la API de Gestión. La API /api/v1/webhooks está deprecada y se eliminará en o después del 1 de noviembre de 2027. La sustitución vive bajo /api/core/webhooks. Qlik dice que ambas rutas usan los mismos recursos de webhooks, por lo que los webhooks existentes, sus IDs y el historial de entrega se mantienen, y cambiar la ruta no afecta a las cargas útiles de entrega.
  • Formato de carga. Qlik anunció la migración a CloudEvents el 2 de septiembre de 2025, y ha enviado cargas híbridas (campos heredados más CloudEvents) desde el 3 de noviembre de 2025. El 2 de octubre de 2026 movió el cambio a CloudEvents-only desde el 6 de octubre hasta el 10 de diciembre de 2026. Las integraciones que lean eventId, eventTime, eventType, cloudEventsVersion, contentType o extensions deben pasar a los equivalentes de CloudEvents antes de ese momento.
  • Tipos de eventos. Los eventos del sistema de identidad y gestión de acceso heredados están obsoletos a favor de los eventos com.qlik.core.* y se eliminarán en o después del 30 de noviembre de 2026. Este aviso cubre una familia específica de eventos, no todos los tipos com.qlik.*.

Una advertencia de herramientas: según el aviso de Qlik del 3 de noviembre de 2026, qlik-cli 3.4.0 y @qlik/api 2.20.0 siguen llamando a los endpoints obsoletos /api/v1/webhooks. Hasta que se publiquen versiones actualizadas, los scripts que los usan deben hacer llamadas REST directas para llegar a /api/core/webhooks.

GitLab es la historia de advertencia. La incidencia #588235, la última edición en 30 de enero de 2026, enumera cuatro brechas:

  • Los webhooks no transportan un identificador de versión.
  • Los campos obsoletos no tienen un cronograma de eliminación.
  • Los usuarios no pueden optar por probar formatos más nuevos antes de que se apliquen los cambios.
  • La documentación marca los campos como obsoletos, pero siguen enviándose.

Algunos campos de fusiones de merge request han estado obsoletos desde GitLab 8.5, y la incidencia describe que el enfoque actual, puramente aditivo, es “más o menos nuestro estado actual”. Las API REST de Qlik toman el enfoque opuesto. Envías un encabezado qlik-api-version y las depreciaciones llegan como deprecation, sunset y link en los encabezados de respuesta. Qlik también advierte que una fecha de puesta en escena (sunset) es la fecha de eliminación más temprana, no una garantía.

¿Por qué lado a lado es mejor que un gran corte?

Un registro de cambios te dice lo que el proveedor pretende. El tráfico capturado te dice lo que realmente llega: cabeceras, nombres de campos, tipos, anidación y comportamiento de reintentos. Las guías de Penneo documentan endpoints, tipos de eventos y el encabezado de firma, pero no publican una diferencia campo por campo entre v1 y v2. Solo aprendes eso al recibir ambos.

Penneo también indica que tu endpoint debe ser público y que localhost o URLs de red privada no funcionarán. Un túnel llena ese vacío. Los subdominios estables importan porque registras cada URL de callback una sola vez en lugar de editar suscripciones cada vez que cambia una URL aleatoria.

Penneo sugiere una herramienta como Webhook.site para una primera mirada al JSON entrante y a las cabeceras. Eso funciona para una comprobación rápida. Un receptor local detrás de un subdominio estable te permite conservar cuerpos crudos en disco y reproducirlos contra tu manejador real.

Paso 4: Verifica la firma v2 en el cuerpo crudo

La cabecera X-Event-Signature de Penneo es una lista separada por comas de pares clave=valor:

  • t es la marca de tiempo Unix.
  • h es una lista separada por espacios de los nombres de encabezados firmados.
  • v1 es la firma.

Un ejemplo documentado se ve como t=1763132484,h=x-event-id x-event-type,v1=abc123....

La cadena firmada es la marca de tiempo, la lista de nombres de encabezados, los valores de esos encabezados y el cuerpo crudo de la solicitud, todo unido con puntos. La firma es un digest HMAC-SHA256 calculado con la clave secreta de la suscripción y comparado en tiempo constante. Penneo recomienda rechazar las marcas de tiempo fuera de una ventana, como ±5 minutos, y rechazar IDs de evento que ya hayas procesado.

// verify.mjs
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyPenneo(headers, rawBody, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    String(headers["x-event-signature"] ?? "").split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i).trim(), p.slice(i + 1)];
    }));
  if (!parts.t || !parts.h || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;

  const values = parts.h.split(" ").map((n) => headers[n.toLowerCase()] ?? "");
  const signed = [parts.t, parts.h, ...values].join(".") + "." + rawBody;
  const expected = createHmac("sha256", secret).update(signed).digest("hex");

  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

Always pass the raw bytes you received, never re-serialized JSON, because whitespace changes break the digest. Also dedupe on X-Event-Id, since delivery is at-least-once. Penneo suggests caching event IDs for a short period, such as the same duration as your timestamp window.

Atajos del túnel específicos de v2

  • Responde rápido. Con un límite de conexión de 500 ms y un límite de respuesta de 1.5 segundos, haz lo mínimo en el manejador: verifica, encola, devuelve 2xx.
  • Nunca redirijas. Un 3xx cuenta como fallo y se vuelve a intentar, por lo que una redirección HTTP→HTTPS o con barra final en tu endpoint provoca reintentos.
  • Un túnel muerto no es inofensivo. Cuando una entrega falla, Penneo reintenta hasta 5 veces a intervalos que comienzan en 5 segundos y crecen en 5 segundos cada vez. Luego reintenta cada hora, hasta 30 veces. Después de los 35 reintentos se detiene y desactiva automáticamente la suscripción, luego envía un correo al usuario que la creó y a los administradores del cliente. Según mi cálculo, eso es aproximadamente 30 horas después de la primera falla. Una suscripción de sandbox apuntando a un túnel detenido durante un fin de semana largo será desactivada, y alguien debe actualizarla manualmente y reactivarla.
  • Observa los límites de sesión de tu túnel. Si tu plan de túneles limita la duración de sesión, un túnel que cae y vuelve a conectarse puede dejarte depurando entregas perdidas. Verifica los límites de tu plan y utiliza los registros de entrega en Configure → Webhooks.
  • Respeta el límite de cinco suscripciones. El límite se documenta como 5 suscripciones activas por cliente en el nuevo servicio. La documentación no dice si las suscripciones v1 antiguas cuentan, así que no asumas margen mientras ambas versiones están en funcionamiento.

La checklist de corte

  1. Inventario de cada suscripción v1 (GET {base}/api/v1/webhook/subscriptions) y de cada ruta de código que llama a /api/v1/webhook.
  2. Mapea cada tema v1 a tipos de evento v2. Por ejemplo, “casefile” se asigna a los cuatro tipos sign.casefile.*, y las notificaciones de firmantes se asignan a los tipos relevantes sign.signer.*.
  3. Crea la suscripción de prueba v2, activa webhook.subscription.test y confirma la recepción en el túnel v2.
  4. Captura los mismos eventos reales en ambos túneles y ejecuta diff.mjs. Corrige cada diferencia de campo, tipo y cabecera.
  5. Agrega verificación de firmas y idempotencia de X-Event-Id al manejador v2.
  6. Reconoce primero. Mueve el trabajo lento a una cola para mantener las respuestas dentro de 1.5 segundos.
  7. Crea la suscripción de producción v2 en {base}/webhook/api/v1. Mantén la superposición corta, ya que activar ambas versiones genera notificaciones duplicadas.
  8. Elimina las suscripciones antiguas con DELETE {base}/api/v1/webhook/subscriptions/{subscriptionId} una vez confirmada latráfico de v2.
  9. Observa los registros de entrega (Configure → Webhooks en Penneo) durante unos días, luego libera los subdominios del túnel que ya no uses.
  10. Repite para Qlik y GitLab, como se describe a continuación.

Qlik: tres cambios, tres pruebas

1. Ruta de la API de Gestión (para noviembre de 2027). La migración es mecánica. Reemplaza /api/v1/webhooks por /api/core/webhooks y mantiene el resto de la ruta, parámetros de consulta y cuerpos de las solicitudes sin cambios. El aviso de Qlik enumera diez reemplazos directos de endpoints, cubriendo listar, crear, obtener, parchear, poner, eliminar, entregas, detalles de entrega, reenviar y tipos de evento. Prueba primero en un inquilino no de producción.

2. Formato de carga (10 de diciembre de 2026). Usa la reproducción de carga reducida del Paso 3. Qlik documenta cargas útiles con CloudEvents únicamente a partir de esa fecha.

3. Tipos de eventos del sistema (a partir del 30 de noviembre de 2026). Si tu suscripción utiliza un evento heredado de identidad y gestión de accesos, cambia al tipo mapeado com.qlik.core.*. Algunas mappings renombran más que el prefijo:

Tipo de evento heredado Reemplazo
com.qlik.v1.user.created com.qlik.core.user.created
com.qlik.user-session.begin com.qlik.core.user-session.begun
com.qlik.group.config.updated com.qlik.core.group-setting.updated

Qlik dice que solo com.qlik.v1.user.created, com.qlik.v1.user.deleted y com.qlik.v1.api-key.validation.failed de ese aviso están disponibles a través de Webhooks de Qlik Cloud. Durante cualquier periodo de solapamiento, elimina duplicidades usando el identificador CloudEvent id para evitar procesar el mismo cambio dos veces.

La política de versionado de Qlik (un encabezado qlik-api-version con lanzamientos trimestrales YYYY-MM, cada uno soportado 12 meses) rige las API REST. Los eventos del sistema no usan ese encabezado. Sus depreciaciones están documentadas en las especificaciones AsyncAPI, así que lee esas especificaciones, no solo los encabezados de respuesta.

GitLab: crea tu propio versionado

Como GitLab no ofrece vista previa opcional, haz la tuya. Guarda payloads reales como fixtures y compáralos cada vez que actualices GitLab. Para webhooks de merge request, la incidencia #588235 enumera estos campos obsoletos y sus reemplazos:

Obsoleto Usarlo en su lugar
repository (nivel superior) project
labels (nivel superior) object_attributes.labels
project.http_url project.git_http_url
project.homepage project.web_url
project.ssh_url project.git_ssh_url
project.url project.git_ssh_url o project.git_http_url
object_attributes.assignee_id object_attributes.assignee_ids
object_attributes.work_in_progress object_attributes.draft

Ninguno de estos tiene fecha de eliminación. Pasarlos ahora significa que no te extrañe si GitLab adopta una política de eliminación más adelante. La misma incidencia plantea opciones como webhooks versionados y depreciación con calendario, pero ninguno está comprometido.

Preguntas frecuentes

¿Qué pasa con los webhooks de Penneo después del 30 de noviembre de 2026? Las suscripciones en el servicio heredado dejan de entregar eventos. Migra primero al servicio v2 en {base}/webhook/api/v1.

¿Necesito una URL pública para probar webhooks localmente? Sí. Penneo dice que localhost y las URLs de red privada no funcionan, así que usa un túnel HTTPS con un subdominio estable.

¿Es la fecha de noviembre de 2027 de Qlik el único plazo? No. Esa fecha cubre la API de gestión /api/v1/webhooks. Los campos de carga heredados entran en diciembre de 2026, y los eventos del sistema heredado de identidad y gestión de accesos se eliminan a partir de noviembre de 2026.

¿Cambiará el camino de Webhooks de Qlik mis webhooks existentes? Según Qlik, no. Los webhooks existentes, sus IDs y el historial de entrega se conservan, y el cambio de ruta no afecta a las cargas útiles de entrega.

¿Cuántos túneles necesito? Dos para una prueba lado a lado, uno por versión de carga. Un tercero te permite mantener tu propia app alcanzable al mismo tiempo, si tu plan lo permite (tres túneles simultáneos).

Fuentes

Continue from this article into the most relevant product guides and workflows.

Related Topics

#webhook migration#webhook v1 to v2 migration#webhook deprecation#webhook v1 shutdown#webhook versioning#webhook testing on localhost#localhost tunneling#localhost tunnel#test webhooks locally#webhook payload diff#compare webhook payloads#webhook cutover checklist#webhook migration guide#webhook migration checklist#legacy webhook decommission#webhook API deprecation#deprecated webhook fields#webhook breaking changes#side by side webhook testing#webhook payload comparison#custom subdomain tunnel#free custom subdomain#stable tunnel URL#persistent tunnel URL#multiple concurrent tunnels#ngrok alternative#free ngrok alternative#localhost tunneling tools#expose localhost to internet#webhook debugging#webhook development#webhook endpoint testing#webhook receiver#webhook handler#webhook best practices#webhook backward compatibility#API versioning#API migration#API deprecation strategy#zero downtime migration#webhook signature verification#webhook retry handling#webhook idempotency#Penneo webhook migration#Penneo webhook deprecation#Qlik webhooks API deprecation#GitLab webhooks versioning#developer infrastructure#DevOps tools#cloud-native development#local development environment#HTTPS tunnel#secure tunnel for developers#webhook inspector#request replay#payload schema validation#JSON payload diff#integration testing#third-party API integration#SaaS webhook changes

Keep building with InstaTunnel

Read the docs for implementation details or compare plans before you ship.

Share this article

More InstaTunnel Insights

Discover more tutorials, tips, and updates to help you build better with localhost tunneling.

Browse All Articles