Webhooks que esperan: presupuestos de latencia para eventos sincrónicos
Stripe permite 2 segundos, Shopify 5. Aprenda a medir la latencia de salto del túnel, construir un presupuesto de latencia de webhooks y mantener rápidos los controladores locales.

Quick answer
Presupuestos de latencia de Webhook: Stripe 2s y Shopify 5s: webhook testing answer
For local webhook testing, run your app locally, expose it with a public HTTPS tunnel, and paste the stable callback URL into the provider dashboard.
How do I test webhooks on localhost?
Start your local server, open a public HTTPS tunnel to that port, configure the provider webhook URL, and inspect events in your local logs.
Why does a stable webhook URL matter?
Stable URLs prevent provider dashboards from needing manual callback updates every time you restart a tunnel.
La mayoría de los webhooks son educados. Un proveedor envía un evento, tu servidor dice “lo tengo,” y todo lo demás sucede después. Algunos webhooks no son nada educados. Detienen una transacción real y esperan a que respondas.
Si desarrollas esos manejadores en una laptop detrás de un túnel, tienes un problema nuevo: el reloj ya está corriendo, y el salto por el túnel es una porción de ese tiempo. Esta guía describe cuáles son los presupuestos hoy, cómo medir cuánto de cada presupuesto consume tu túnel y cómo mantener un manejador local lo suficientemente rápido para que pruebes tu lógica y no tu suerte.
Los dos presupuestos que importan ahora
Stripe Issuing: 2 segundos, y la respuesta es la decisión
Cuando se usa una tarjeta emitida a través de Stripe Issuing, Stripe verifica que tu saldo de Issuing tenga fondos suficientes, que la tarjeta esté activa y que tus controles de gasto permitan la compra. Si la autorización supera esas comprobaciones y has configurado un webhook de autorización en tiempo real, Stripe envía un evento issuing_authorization.request a tu endpoint. Si no apruebas o rechazas dentro de 2 segundos, Stripe aprueba o rechaza la autorización por ti, según tus ajustes de tiempo de espera en la configuración de Issuing del Panel, o en tus ajustes de Autopilot si los has configurado.
Si necesitas más contexto, consulta las secciones a continuación para entender cómo diseñar para este caso y qué implica cada detalle.
- La respuesta es la decisión. Respondes directamente al webhook con un estado
200y un cuerpo JSON. El campoapprovedes requerido. El encabezadoStripe-Versiontambién es obligatorio en la respuesta, yapplication/jsones el único tipo de contenido aceptado. - El fallo tiene un nombre. Cuando el
request_history.reasonde una autorización eswebhook_errorowebhook_timeout, Stripe no está recibiendo tus respuestas.webhook_errorsignifica que respondiste con una versión de Stripe API inválida en los encabezados de la solicitud, o Stripe no pudo procesar tu respuesta.webhook_timeoutcubre todos los demás modos de fallo. Stripe también advierte contra usar la banderaapprovedpara juzgar la salud de la integración, porque Autopilot puede aprobar en tu nombre durante un error. Su propio ejemplo de algo que investigar es una autorización conapproved: trueperorequest_history.reason: webhook_error. Suscríbete aissuing_authorization.createdyissuing_authorization.updatedpara vigilar estos casos, y leerequest_history.reason_messagepara obtener el texto de error detallado. - Existen fallbacks, pero no son tu lógica. Autopilot, actualmente en vista pública previa, toma decisiones en tu nombre a partir de un conjunto de reglas predefinidas cuando tus sistemas están caídos, no responden o devuelven una respuesta inválida. Lo configuras contactando al soporte de Stripe. Un Autopilot separado de Stripe (también en vista previa pública) es para usuarios con su propio BIN dedicado. Ayuda cuando la red de tarjetas no puede contactar con Stripe, y esas decisiones se etiquetan como
network_fallback. Ninguno de los dos es un sustituto de responder a tiempo. - No todas las compras te llegan. Solo las solicitudes de autorización van al endpoint síncrono. Otras notificaciones van a tu endpoint de webhook habitual. Si tu saldo de Issuing es demasiado bajo, la autorización se niega y tu webhook nunca ve la solicitud. Las denegaciones por control de gasto también ocurren del lado de Stripe. Si no tienes configurado un webhook en tiempo real, Stripe aprueba autorizaciones que cumplen sus propias comprobaciones sin enviar la solicitud.
Por qué esto, de pronto, es problema de todos
La documentación de Stripe para Issuing para agentes describe dar a cada agente su propia tarjeta virtual con límites de gasto por agente, controles de categoría de comerciante y reglas de autorización personalizadas. También indica que una vez que pasas una tarjeta a un agente, cada intento de compra activa una solicitud de autorización en tiempo real antes de que se procese el cargo. La misma página dice que hay un tiempo de espera predeterminado de 2 segundos para responder antes de que Stripe recurra a las reglas predeterminadas de la tarjeta.
La guía de Stripe para checkout programático añade un segundo camino. Cuando un vendedor canjea un Shared Payment Token (SPT) financiado por una tarjeta Issuing, el cargo pasa por tu ruta existente de autorización en tiempo real de Issuing, antes de la captura y liquidación. Esa guía dice que crear un PaymentMethod a partir de una tarjeta Issuing requiere acceso de vista previa privada, y las solicitudes SPT utilizan la versión de API de vista previa 2026-04-22.preview. Trata ese flujo como algo que verificar contra la documentación actual antes de construir sobre ello.
En otras palabras, que un agente comprando algo es ahora una fuente normal de eventos issuing_authorization.request, y cada uno de ellos tiene un reloj de dos segundos.
Shopify: 5 segundos, y la respuesta es un acuse de recibo
La documentación de resolución de problemas de webhooks de Shopify dice que tu app debe responder dentro de cinco segundos, y que un estado de la serie 200 cuenta como éxito. Su guía para manejadores lentos es retrasar el procesamiento hasta después de enviar una respuesta.
Las consecuencias de no cumplir la ventana también se detallan:
- Shopify intenta de nuevo las entregas fallidas hasta ocho veces en un periodo de cuatro horas, y el intervalo antes de cada reintento aumenta.
- Si los fallos persisten, la suscripción se elimina. Las suscripciones eliminadas no reciben nada hasta que las vuelvas a crear.
- El Dev Dashboard muestra tu tiempo de respuesta en el percentil 90 y tu tasa de entregas fallidas. Las tasas de fallo superiores al 0.5% se describen como superiores a la media. Tiempos de respuesta entre cuatro y cinco segundos se marcan como peligrosamente cercanos al límite.
La diferencia entre los dos proveedores es el punto de diseño clave:
Stripe issuing_authorization.request |
Shopify webhooks | |
|---|---|---|
| Ventana | 2 segundos | 5 segundos |
| Qué devuelves | La propia decisión | Un acuse de recibo 2xx |
| Trabajo después de responder | No es posible para la decisión | Esperado, y recomendado |
| En caso de fallo | Tus ajustes de tiempo de espera (o Autopilot) deciden | Reintentos hasta 8 veces, luego eliminación de la suscripción |
Con Shopify puedes engañar al reloj reconociendo rápido y trabajando más tarde. Con Stripe Issuing no puedes, porque el trabajo que pospondrías es lo que Stripe está esperando.
Anatomía de un presupuesto de 2000 ms
Trata la ventana como un presupuesto que gastas, no como un límite que esperas mantener. Para un webhook síncrono, el tiempo entre Stripe enviando la solicitud y recibiendo tu respuesta se desglosa aproximadamente así:
- Stripe hacia el borde del túnel (tránsito por Internet, TLS)
- Borde del túnel al agente del túnel en tu máquina (el propio túnel)
- Agente a tu servidor local (loopback, prácticamente gratis)
- Tu controlador (análisis, verificación, lógica de decisión, cualquier E/S)
- El mismo camino de salida
Aquí tienes una asignación ilustrativa. Estos son números de planificación, no mediciones de ningún servicio:
| Segmento | Margen de planificación |
|---|---|
| Red entrante y TLS | 100–300 ms |
| Salto de túnel, ambas direcciones | 50–200 ms |
| Verificación de firma y análisis | menos de 10 ms |
| Lógica de decisión | menos de 100 ms |
| Margen de seguridad | 800 ms o más |
Observa lo que implica la tabla. Si tu controlador hace una consulta fría a la base de datos o una llamada API saliente, puedes agotar el margen sin darte cuenta, y el túnel no es el culpable. La única forma de saberlo es medir.
Una regla útil es establecer una fecha límite interna bien dentro de la ventana del proveedor, por ejemplo 800 a 1,000 ms para Stripe, y hacer que tu controlador devuelva su mejor respuesta para entonces, sin importar el estado de sus dependencias. Si decides un tiempo de espera por tu cuenta, eliges la decisión de fallback. Si decide el reloj de Stripe, tus ajustes del Panel (o Autopilot) la eligen para ti.
Medición del salto del túnel
No puedes restar aquello que no has medido. Usa tres mediciones y compáralas.
1. Tiempo del propio controlador
Instrumenta tu propio código. Este es el valor que el túnel no puede afectar. Aquí tienes un ejemplo mínimo de Node y Express que reporta su propia duración con el encabezado estándar Server-Timing:
import express from "express";
const app = express();
app.use(express.raw({ type: "application/json" }));
app.post("/stripe/issuing", (req, res) => {
const start = process.hrtime.bigint();
// 1. Verifica el encabezado Stripe-Signature contra req.body (los bytes en crudo),
// por ejemplo con stripe.webhooks.constructEvent().
// 2. Ejecuta tu lógica de decisión.
const decision = { approved: true };
const ms = Number(process.hrtime.bigint() - start) / 1e6;
console.log(JSON.stringify({ route: "issuing", handler_ms: ms }));
res.status(200);
res.set("Stripe-Version", "2025-03-31.basil"); // use a supported version, see Stripe's API versioning docs
res.set("Server-Timing", `handler;dur=${ms.toFixed(1)}`);
res.json(decision);
});
app.listen(3000);
El valor de Stripe-Version anterior es el que se utiliza en el propio ejemplo de Stripe. Consulta la página de versionado de API de Stripe para ver los valores compatibles, porque un encabezado de versión inválido es una causa documentada de webhook_error. Los docs de Stripe también recomiendan verificar las firmas de webhook y permitir listas de direcciones IP de Stripe para que solo actúes ante eventos genuinos de Stripe.
2. Medir el tiempo de la solicitud de extremo a extremo con curl
curl puede dividir una solicitud en etapas. Cada valor es una marca de tiempo acumulativa desde el inicio de la solicitud:
curl -s -o /dev/null -X POST "https://YOUR-SUBDOMAIN.example-tunnel.dev/stripe/issuing" \
-H "Content-Type: application/json" -d '{"test":true}' \
-w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} first_byte=%{time_starttransfer} total=%{time_total}\n'
Ejecuta el mismo comando contra http://localhost:3000/stripe/issuing. La diferencia entre los dos valores total, tomada en varias ejecuciones, es la sobrecarga del túnel vista desde tu posición. Para un controlador que verifica firmas, una solicitud de prueba no firmada será rechazada temprano. O bien añade una excepción de prueba o envía una carga útil firmada correctamente.
3. Compara percentiles, no promedios
Un presupuesto se rompe por la cola lenta, no por la mediana. Ejecuta un par de cientos de solicitudes en cada dirección y compara p50, p95 y p99:
URL="https://YOUR-SUBDOMAIN.example-tunnel.dev/stripe/issuing"
for i in $(seq 1 200); do
curl -s -o /dev/null -w '%{time_total}\n' -X POST "$URL" \
-H "Content-Type: application/json" -d '{}'
done | sort -n | awk '{a[NR]=$1} END {print "p50="a[int(NR*0.50)], "p95="a[int(NR*0.95)], "p99="a[int(NR*0.99)]}'
Saber lo que tu medición deja fuera
Sé honesto sobre los límites de la medición en la laptop. Cuando llamas a tu propia URL del túnel desde la misma máquina, la solicitud sale de tu red, llega al borde y regresa por el túnel hacia ti. Ese camino de curva no es el camino que siguen los servidores de Stripe, por lo que puede sobrestimar o subestimar la latencia de entrada real. Dos formas de afinarlo:
- Ejecuta el bucle
curldesde una pequeña VM en la nube en una región cercana al origen probable del proveedor, para que la pierna de entrada se asemeje a la realidad. - Registra una marca de tiempo de recepción en tu controlador y compárala con el tiempo de creación del propio evento. Las marcas de tiempo de Stripe están en segundos completos y tu reloj podría estar desajustado, así que usa esto solo para detectar retrasos grandes, no para medir milisegundos.
Usando los registros de requests para ver qué pasó realmente
Las mediciones de un bucle te dicen qué es posible. Los registros de requests te dicen qué pasó cuando el proveedor real llamó. Cuando una autorización de Stripe regresa como webhook_timeout, quieres responder a una pregunta: ¿llegó la solicitud a mi máquina en absoluto, y qué hizo tu controlador con ella?
El CLI de InstaTunnel documenta un flag --logs que obtiene registros de requests en vivo, y señala que los registros de requests requieren el plan Pro o Business. Eso te brinda un registro de las solicitudes que cruzaron el túnel, que puedes comparar con los registros de tu propio controlador y con request_history de Stripe para la misma autorización. Un flujo de trabajo práctico:
- Encuentra la autorización en Stripe y toma nota de su
request_history.reasonyreason_message. - Encuentra la solicitud coincidente en los registros de requests del túnel. Si falta, el problema está upstream de tu laptop. Si está presente, el problema está en tu controlador o después de él.
- Empareja eso con la línea de registro estructurada de tu controlador y su valor
handler_ms.
Mantén el registro de duración de tu controlador como fuente de verdad de cualquier modo, ya que la vista de registros del túnel es un registro de tráfico y no un sustituto para medir tu propio código.
Del lado de Shopify, la página de Logs del Dev Dashboard enumera entregas individuales de los últimos 7 días, filtrables por tema, estado y tienda. Shopify señala que esta vista no es en tiempo real y que los datos pueden retrasarse por varios minutos, así que no concluyas que una entrega falta justo después de fallar.
Mantener rápido un controlador en una laptop
Una laptop es un buen lugar para construir un controlador síncrono y un lugar poco indulgente para ejecutarlo si ignoras sus hábitos. Estas son las formas comunes en las que los controladores locales pierden su presupuesto.
Elimina rutas en frío
La primera solicitud tras un periodo de inactividad suele ser la más lenta. Los pools de conexiones están vacíos, las cachés están frías, y un runtime de lenguaje podría estar calentándose. Antes de una prueba, envía unas cuantas solicitudes descartables. Durante la prueba, mantén vivos los clientes de base de datos y HTTP y reutiliza las conexiones en lugar de abrir una nueva por solicitud.
Decide desde la memoria
Para Stripe Issuing, diseña la decisión para que no requiera ningún viaje de red. Carga las reglas de gasto, listas de permitidos por categoría de comerciante y límites por tarjeta en la memoria al inicio y actualízalas mediante un temporizador. la carga útil de autorización ya lleva los detalles del comerciante y los metadatos que adjuntaste a la tarjeta, y la documentación de Stripe para el agente sugiere comprobaciones comunes como emparejar el negocio con la tarea del agente, confirmar el importe contra el presupuesto esperado y señalar una velocidad de transacción inusual. Todo esto puede ejecutarse sobre datos en el proceso. Una decisión que lee unos pocos mapas en memoria toma microsegundos. Una decisión que espera a una base de datos remota es una lotería frente al reloj.
Si tu plataforma de agentes quiere un modelo para juzgar una compra, haz ese análisis por adelantado y cachea el veredicto, o haz que el modelo configure los controles de la tarjeta por adelantado. Los docs de Stripe dicen que los límites de gasto y los controles de categorías de merchant se configuran en la creación de la tarjeta y pueden actualizarse en cualquier momento. Una llamada de modelo dentro de la ventana de dos segundos es el lugar más caro para poner un juicio que podrías haber codificado antes.
Coloca cada llamada saliente dentro de un plazo
Envuelve cualquier cosa que pueda bloquearse en un timeout, y haz explícito el fallo por defecto:
const controller = new AbortController();
const timer = setTimeout(() =\u003e controller.abort(), 400);
try {
const risk = await fetch(RISK_URL, { signal: controller.signal });
// use the result
} catch {
// timed out: apply your documented default policy
} finally {
clearTimeout(timer);
}
Elige el valor por defecto de forma deliberada. Rechazar protege el gasto pero frustra una compra legítima. Aprobando mantiene a los agentes funcionando pero expande la exposición. Cualquiera que elijas, anótalo, porque de lo contrario Stripe aplicará lo que digan tus ajustes de tiempo de espera.
Domar la máquina
- Power y sleep. Un portátil con batería puede reducir la potencia de la CPU, y un portátil en modo de suspensión no responde. Mantente conectado a la corriente y mantén la máquina despierta durante las pruebas.
- Jitter de Wi‑Fi. Enlaces inalámbricos añaden retardos variables que la mediana oculta y el p99 revela. Realiza pruebas al menos una vez con Ethernet para ver cuánta es tu radio.
- Carga de fondo. Una compilación local, un contenedor descargando imágenes o un cliente de sincronización puede robar CPU justo cuando llega una solicitud. Verifica qué más se está ejecutando antes de fiarte de un número malo.
- Modo de depuración. Un depurador detenido en un punto de interrupción arruinará cualquier presupuesto. Usa registros, no puntos de interrupción, para pruebas de latencia.
Reconoce primero cuando el proveedor te lo permita
Para Shopify, devuelve 200 en cuanto se reciba y verifique el payload, luego encola el trabajo real. Persistir el evento en bruto a una cola local o archivo antes de responder, para que un fallo después del acuse no pierda datos. Como los reintentos pueden hacer que el mismo evento llegue más de una vez, haz que el procesamiento descendente sea idempotente. La página de “Verify deliveries” de Shopify cubre la verificación HMAC y el manejo de entregas duplicadas. Si tu app se des conecta por mucho tiempo, el consejo de recuperación de Shopify es re-suscribirse donde haga falta y volver a importar los datos faltantes.
Lista de verificación previa
Haz esto antes de registrar una URL de túnel con un proveedor para eventos sincrónicos:
- Conoce la ventana: 2 segundos para autorizaciones en tiempo real de Stripe Issuing, 5 segundos para webhooks de Shopify.
- Establece una fecha límite interna bien dentro de la ventana.
- Mide el tiempo del controlador, luego el tiempo total a través del túnel, en p50, p95 y p99.
- Calienta el controlador y reutiliza conexiones.
- Mantén los datos de decisión en memoria.
- Da a cada llamada saliente un límite de tiempo duro y un fallback explícito.
- Para Stripe, devuelve la decisión directamente con un encabezado
Stripe-Versionválido, verifica firmas y vigilarequest_history.reasonparawebhook_errorywebhook_timeout. - Para Shopify, reconoce primero, encola el trabajo y vigila el tiempo de respuesta p90 y la tasa de fallos del Dev Dashboard.
- Mantén estable la URL del túnel entre ejecuciones para registrarla una vez.
- Revisa los registros de requests después de cada fallo.
Pruebas sin esperar una tarjeta real
No necesitas una tarjeta física para ejercitar la ruta. Stripe ofrece helpers de prueba de Issuing, incluido un API de Authorization Create que simula una nueva autorización en una tarjeta Issuing. Existen helpers correspondientes para autorizaciones incrementales y reversiones. Configura tu endpoint de autorización en tiempo real en la configuración de Issuing con tu URL de túnel, crea autorizaciones a través del helper y observa lo que llega. Ejecuta en lotes para ver el comportamiento de cola y no una única solicitud afortunada.
Los docs de Stripe también describen un bucle local más liviano. stripe listen --forward-to localhost:4242/webhook reenvía eventos a tu servidor, y stripe trigger issuing_authorization.request dispara un evento de prueba desde el CLI. Eso es útil para verificar tu lógica. Para medir la latencia del túnel, envía tráfico a través del propio túnel.
Para Shopify, el Dev Dashboard te permite activar una entrega actualizando tu tienda de desarrollo, por ejemplo creando un producto para disparar products/create, y luego leer el tiempo de respuesta de la entrega.
La conclusión
Los webhooks síncronos convierten la latencia en un requisito de corrección. Stripe te da 2 segundos para tomar una decisión. Shopify te da 5 para emitir un acuse de recibo. Ninguna de las dos ventanas es generosa una vez que añades Internet, un túnel y una laptop que también está ejecutando tu editor.
La buena noticia es que el presupuesto es fácil de gestionar una vez dejes de adivinar. Mide tu controlador, mide la ruta completa, observa la cola, mantiene decisiones en memoria, pon deadlines a cada llamada saliente y lee los registros de request cuando algo falla. Haz eso, y el túnel se convertirá en un solo ítem pequeño y conocido en lugar del sospechoso en cada timeout.
Fuentes
- Stripe: Autorizaciones en tiempo real de Issuing
- Stripe: Autorizaciones de Issuing
- Stripe: Issuing para agentes
- Stripe: Paga con un Shared Payment Token desde una tarjeta Issuing
- Shopify: Solucionar problemas de webhooks
- InstaTunnel: CLI README
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Related Topics
Keep building with InstaTunnel
Read the docs for implementation details or compare plans before you ship.