What breaks when you start a workflow with lookup-then-start?

Starting a workflow with getHookByToken() followed by start() leaves a gap where duplicate starts slip through. Atomic start hooks let one start() call admit a run and claim a hook, using your own domain token as the idempotency key.

What it is

The Workflow SDK's start() can now admit a run and claim a hook in one atomic step. The token comes from your domain, like an order ID, and exactly one run owns it.

Applied case

A developer processing orders previously used getHookByToken() followed by start(), which had a documented duplicate-start race. Now they call start() with an order ID as token: the first run claims it, and a duplicate start() throws HookConflictError carrying the owner's conflictingRunId, never becoming a run. Setting experimental_minRetention keeps the token unavailable after the run ends, so late duplicates are still refused.

• Pass your order ID as token: one run owns it, duplicates throw HookConflictError with conflictingRunId

When to use it

Use when you need exactly-once workflow starts keyed by domain IDs like orders or invoices. / Skip when duplicate starts are harmless or already deduped upstream.

Read more

Atomic start hooks in the Workflow SDK

Idempotency docs