Un comprador toca dos veces «Crear pedido» porque la pantalla tardó en responder. Si tu ruta inicia dos workflows, puedes enviar dos correos, generar dos facturas o incluso cobrar dos veces. El 4 de noviembre de 2026, Vercel anunció un inicio atómico para Workflow SDK: una clave de negocio se reclama al crear la ejecución, de modo que la segunda llamada conoce cuál fue la primera. Es una mejora concreta para automatizaciones que reciben reintentos, webhooks o clics duplicados.
La carrera que elimina
El patrón anterior consultaba getHookByToken() y después llamaba a start(). Dos solicitudes simultáneas podían ver «no existe» antes de iniciar, y ambas creaban un run. El anuncio de Vercel describe que start() ahora admite y reclama el Hook en una sola operación atómica. La segunda llamada con el mismo token lanza HookConflictError; conflictingRunId identifica al dueño. La guía oficial indica instalar workflow 5.4.0 o posterior y usar un World compatible.
La clave debe representar la operación real: order:123, invoice:abc o import:2026-11-05. Un token nuevo en cada reintento no protege nada. Tampoco conviene usar solo el ID de usuario, porque dos pedidos legítimos de esa persona quedarían bloqueados entre sí.
El núcleo copiable para una ruta de Next.js
En un proyecto que ya usa Workflow SDK, el ejemplo oficial se reduce a este patrón. processOrder es tu workflow existente; valida y autoriza orderId antes de aceptar la petición. La respuesta duplicada devuelve el run original y no inicia otra ejecución:
import { start } from "workflow/api";
import { HookConflictError } from "workflow/errors";
import { processOrder } from "./workflows/process-order";
export async function POST(request: Request) {
const { orderId } = await request.json();
if (typeof orderId !== "string" || !orderId) {
return Response.json({ error: "orderId required" }, { status: 400 });
}
try {
const run = await start(processOrder, [orderId], {
experimental_hook: { token: `order:${orderId}` },
});
return Response.json({ runId: run.runId, duplicate: false });
} catch (error) {
if (!HookConflictError.is(error)) throw error;
return Response.json({
runId: error.conflictingRunId,
duplicate: true,
});
}
}Para comprobarlo, envía dos solicitudes concurrentes con el mismo ID de prueba. Debes obtener un único runId: una respuesta con duplicate:false y otra con duplicate:true. Repite con otro ID y confirma que sí nace otra ejecución. La respuesta HTTP no demuestra por sí sola el efecto de negocio: inspecciona los runs y la tabla o servicio donde se produjo la acción.
El límite importante: un run no equivale a un solo cobro
La protección cubre inicios duplicados. Si un paso dentro del mismo run cobra a un proveedor y pierde la confirmación, ese paso podría reintentarse. La guía distingue idempotencia del run de idempotencia de pasos: usa una clave estable como stepId cuando la API externa la soporte, y una restricción única en tu base de datos para operaciones irreversibles. No presentes el Hook como sustituto de esas barreras.
Hay además un límite temporal. Sin retención, el token se libera cuando termina el run; un reintento tardío podría iniciar otro. Si necesitas rechazar duplicados durante días, configura experimental_minRetention para el período que tu negocio exige y comprueba la capacidad del World. Si una segunda solicitud lleva información nueva que el run debe recibir, la documentación ofrece resumeHook; no la uses para reenviar ciegamente el mismo pago.
Estado de la prueba: el patrón y las restricciones se basan en documentación oficial. El bloque se ha revisado contra esa API; no ejecutamos dos runs reales en una cuenta Vercel durante esta publicación. Antes de activarlo en producción, prueba concurrencia, retención, reintentos del proveedor y una operación de bajo riesgo.