Vercel Workflow SDK: arranques idempotentes de workflows

Qué cambió en el Workflow SDK de Vercel

La función start() del Workflow SDK de Vercel ya puede admitir una ejecución y reclamar un hook en un único paso atómico. Con la actualización a la versión 5.3.1, el SDK reemplaza el patrón anterior de consultar el hook con getHookByToken() y arrancar después con start(), un flujo que dejaba una ventana documentada entre la consulta y el arranque donde dos peticiones simultáneas podían crear dos ejecuciones para el mismo evento.

El cambio suena a detalle de implementación, pero ataca uno de los errores más caros y más silenciosos en producción: el trabajo duplicado. Un webhook de pago que llega dos veces, un reintento automático de la pasarela, un doble clic en «confirmar pedido» o un job de importación que se dispara de nuevo pueden ejecutar dos veces el mismo proceso. Cuando ese proceso cobra, factura o envía un correo, el costo deja de ser solo técnico.

El problema real: la carrera entre consultar y arrancar

El patrón anterior obligaba a dos pasos: primero preguntar si el token ya tenía un hook asociado, después arrancar el workflow. Entre esas dos operaciones hay un hueco. Si dos requests entran en ese intervalo, ambas ven el mismo estado — «todavía no hay hook» — y ambas arrancan.

¿Y esto cómo se aplica en tu negocio?

Dueños de negocio de Latinoamérica y España usan un agente de IA para ganar más y recuperar su tiempo. El Kit «tu mano derecha con IA» te muestra cómo en un video de 11 minutos, con una ficha para armar el tuyo. CAR está cerrada por ahora; al anotarte, te avisamos cuando abra.

👥 Quiero el Kit →

Ese hueco es una condición de carrera clásica, y es especialmente peligrosa porque no falla siempre. Falla bajo concurrencia, que es justo cuando el sistema está bajo presión: picos de tráfico, reintentos en cascada, colas que se destraban a la vez. En pruebas con un solo request, el código se ve impecable.

La solución del SDK es mover la verificación y el arranque a una sola operación. Ya no queda intervalo que cubrir.

Cómo funciona la idempotencia con tokens propios

La clave del diseño es que el token lo pones tú, y sale de tu propio dominio: un ID de pedido, de factura, de importación o de request. Ese token es la clave de idempotencia, y por sí solo garantiza que exista una única ejecución dueña.

El flujo queda así:

Llamas a start() pasando el token en experimental_hook.
Si el token está libre, la ejecución se admite y el hook queda reclamado desde ese mismo instante.
Si el token ya tiene dueño, start() lanza un HookConflictError que incluye el conflictingRunId de la ejecución que lo posee. El duplicado nunca llega a convertirse en una ejecución.
En el bloque de captura, puedes redirigir el payload del duplicado a la ejecución original con resumeHook(), para que la información no se pierda.

Dos detalles resuelven casos que suelen doler. Primero: el hook reclamado existe desde que se admite la ejecución, así que resumeHook() funciona incluso antes de que el workflow empiece a ejecutarse, y los payloads que llegan temprano se almacenan en búfer y se entregan en orden. Segundo: dentro del workflow, createHook({ token }) con el mismo token se enlaza al hook ya reclamado — no registra nada nuevo, no añade un paso y getConflict() devuelve null.

También hay un caso que vale la pena conocer: el workflow no está obligado a abrir el hook. Si nunca lo hace, el token funcionó solo como clave de idempotencia y la ejecución termina con normalidad. Y si configuras experimental_minRetention, el token sigue indisponible después de que la ejecución termina, contado desde start(), de modo que los duplicados tardíos también se rechazan.

¿Qué significa esto para tu startup?

Si tu producto procesa pagos, pedidos, importaciones o cualquier operación con efectos secundarios irreversibles, esta actualización te entrega una pieza que antes había que construir a mano — y que casi nadie construye bien.

Tres acciones concretas:

Usa IDs de tu dominio como token, no UUIDs aleatorios por request. Si generas un identificador nuevo en cada llamada, cada reintento parece un evento distinto y la idempotencia no sirve de nada. El token tiene que derivarse del evento real: order:1234, invoice:5678.
Trata HookConflictError como un caso esperado, no como un fallo. No lo dejes caer en el manejador de errores genérico ni devuelvas un 500. Captúralo, recupera el runId del dueño y decide si rediriges el payload o simplemente respondes con éxito, porque el trabajo ya está en marcha.
Revisa tus integraciones de webhooks. Los proveedores de pago reintentan por diseño cuando no reciben respuesta a tiempo. Si tu handler arranca un workflow sin idempotencia, ese reintento es una ejecución nueva.

Un cuarto punto, más de arquitectura: si tu equipo ya usa el SDK para orquestar agentes o procesos largos, el token te permite separar dos conceptos que suelen mezclarse — «este evento ya fue procesado» y «este workflow está escuchando actualizaciones». Ahora el mismo token cubre ambos.

¿Cómo se compara con Temporal, Inngest y Cloudflare?

El Workflow SDK no es la única opción para ejecución durable. En octubre de 2026, MarkTechPost cubrió el lanzamiento de durable-harness, un paquete open source de Vercel bajo licencia Apache-2.0 que envuelve harnesses de agentes como Pi, OpenCode, Claude Code y Codex para que las sesiones sobrevivan a caídas. Según ese medio, el paquete usa la misma maquinaria que impulsa el Workflow SDK, donde un «World» agrupa almacenamiento, cola y stream detrás de una sola interfaz.

En el mismo análisis, MarkTechPost compara el enfoque de Vercel con Temporal + OpenAI Agents SDK (envoltorio de ejecución durable, en disponibilidad general desde marzo de 2026), Inngest AgentKit y Cloudflare Agents SDK. La diferencia de fondo no es la durabilidad — todas la ofrecen — sino dónde vive el estado y cuánta infraestructura tienes que operar tú. El Workflow SDK puede correr en Vercel, en local o autoalojado con un Postgres World, según ese mismo reporte.

Para un equipo pequeño, la pregunta práctica es otra: ¿cuánto tiempo de ingeniería cuesta implementar idempotencia correctamente sobre la herramienta que ya usas? Ahí es donde un cambio como el de la versión 5.3.1 se traduce en semanas ahorradas.

Conclusión

La actualización es pequeña en superficie y grande en consecuencias. Pasar de dos pasos a uno elimina una clase entera de bugs que solo aparecen cuando el sistema está bajo presión, y lo hace sin que tengas que diseñar tu propia capa de idempotencia.

Si tu stack ya está en el Workflow SDK, actualizar a la versión 5.3.1 y migrar el patrón getHookByToken() + start() es una tarea acotada con retorno inmediato. Si estás evaluando herramientas de orquestación durable, mira cómo cada opción resuelve la idempotencia antes de decidir: es una de esas decisiones que se pagan caras cuando se toman por defecto.