workflow 5.0.0-beta.9 → 5.0.1

package/docs/foundations/hooks.mdx

@@ -11,9 +11,9 @@ related:
   - /docs/ai/human-in-the-loop
 ---
 
-Hooks provide a powerful mechanism for pausing workflow execution and resuming it later with external data. They enable workflows to wait for external events, user interactions (also known as "human in the loop"), or HTTP requests. This guide will teach you the core concepts, starting with the low-level Hook primitive and building up to the higher-level Webhook abstraction.
+Hooks pause workflow execution and resume it later with external data. Workflows can wait for external events, user interactions (also known as "human in the loop"), or HTTP requests.
 
-## Understanding Hooks
+## Understanding hooks
 
 At their core, **Hooks** are a low-level primitive that allows you to pause a workflow and resume it later with arbitrary [serializable data](/docs/foundations/serialization). Think of them as suspension points in your workflow where you're waiting for external input.
 
@@ -23,9 +23,9 @@ When you create a hook, it generates a unique token that external systems can us
 - Receiving data from an external system or service
 - Implementing event-driven workflows that react to multiple events over time
 
-### Creating Your First Hook
+### Creating your first hook
 
-Let's start with a simple example. Here's a workflow that creates a hook and waits for external data:
+This workflow creates a hook and waits for external data:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -59,7 +59,7 @@ We recommend using the `using` keyword which implements the [TC39 Explicit Resou
 See the full API reference for [`createHook()`](/docs/api-reference/workflow/create-hook) for all available options.
 </Callout>
 
-### Resuming a Hook
+### Resuming a hook
 
 To send data to a waiting workflow, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) from an API route, server action, or any other external context:
 
@@ -82,12 +82,41 @@ export async function POST(request: Request) {
 
 The key points:
 - Hooks allow you to pass **any [serializable data](/docs/foundations/serialization)** as the payload
-- You need the hook's `token` to resume it
+- You need the hook's `token` to resume it, but knowing the token does not authorize the caller. Check who is calling before `resumeHook()`; see [Security](#security)
 - The workflow will resume execution right where it left off
 
-### Custom Tokens for Deterministic Hooks
+### Checking for token conflicts
 
-By default, hooks generate a random token. However, you often want to use a **custom token** that external systems can reconstruct. This is especially useful for long-running workflows where the same workflow instance should handle multiple events.
+Sometimes you need to know that a hook token has been claimed, but you do not want to wait for external data yet. Await `hook.getConflict()` for that:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOrder(orderId: string): Promise<void>; // @setup
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({
+    token: `order:${orderId}`
+  });
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  // The hook token is registered and reserved here.
+  await processOrder(orderId);
+}
+```
+
+Calling `createHook()` on its own does not register the hook; registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. The conflicting run's accessors are durable steps, so the workflow can inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()`. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies.
+
+### Custom tokens for deterministic hooks
+
+By default, hooks generate their own token. However, you often want to use a **custom token** that external systems can reconstruct. This is especially useful for long-running workflows where the same workflow instance should handle multiple events.
 
 For example, imagine a Slack bot where each channel should have its own workflow instance:
 
@@ -139,9 +168,9 @@ export async function POST(request: Request) {
 }
 ```
 
-### Receiving Multiple Events
+### Receiving multiple events
 
-Hooks are _reusable_ - they implement `AsyncIterable`, which means you can use `for await...of` to receive multiple events over time:
+Hooks are _reusable_. They implement `AsyncIterable`, which means you can use `for await...of` to receive multiple events over time:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -169,7 +198,7 @@ export async function dataCollectionWorkflow() {
 
 Each time you call `resumeHook()` with the same token, the loop receives another value.
 
-### Disposing Hooks Early
+### Disposing hooks early
 
 When a workflow ends, hooks are automatically disposed. However, you may want to release a hook token early so another workflow can use it while your workflow continues running. Use a block scope with `using` to control when disposal happens:
 
@@ -211,9 +240,43 @@ hook.dispose(); // Manually release the token
 After disposal, the hook will no longer receive events and the async iterator will stop yielding values.
 </Callout>
 
-## Understanding Webhooks
+### Taking over a token from another run
+
+Disposing early only works when the run holding the token cooperates. When the newest run should own a token regardless, such as a redeployed bot that must replace the run still waiting on a channel, pass `experimental_force` and let the runtime perform the handoff:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+import { HookForceClaimedError } from "workflow/errors";
+
+declare function processMessage(message: { text: string }): Promise<void>; // @setup
 
-While hooks are powerful, they require you to manually handle HTTP requests and route them to workflows. **Webhooks** solve this by providing a higher-level abstraction built on top of hooks that:
+export async function channelWorkflow(channelId: string) {
+  "use workflow";
+
+  const hook = createHook<{ text: string }>({
+    token: `channel:${channelId}`,
+    experimental_force: true, // [!code highlight]
+  });
+
+  try {
+    for await (const message of hook) {
+      await processMessage(message);
+    }
+  } catch (error) {
+    if (HookForceClaimedError.is(error)) { // [!code highlight]
+      // A newer run for this channel took the token. Wrap up and exit.
+      return { replacedBy: error.claimedByRunId };
+    }
+    throw error;
+  }
+}
+```
+
+The run that held the token is woken and its `await hook` (or `for await...of`) rejects with [`HookForceClaimedError`](/docs/api-reference/workflow-errors/hook-force-claimed-error) once it has drained the payloads it received before the takeover. Every `resumeHook()` for the token from then on reaches the new run, including one that was already in flight, so senders never notice the handoff. Several runs forcing the same token at once chain in the same way and always end with exactly one owner. A run started at a spec version below 8 cannot be taken from; the forced hook then gets an ordinary `HookConflictError`. See [`createHook()`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds) for the full semantics.
+
+## Understanding webhooks
+
+Hooks require you to manually handle HTTP requests and route them to workflows. **Webhooks** provide a higher-level abstraction built on top of hooks that:
 
 1. Automatically serializes the entire HTTP [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object
 2. Provides an automatically addressable `url` property pointing to the generated webhook endpoint
@@ -222,16 +285,16 @@ While hooks are powerful, they require you to manually handle HTTP requests and
 When using Workflow SDK, webhooks are automatically wired up at `/.well-known/workflow/v1/webhook/:token` without any additional setup.
 
 <Callout type="warn">
-`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. This is convenient for prototypes and a simple developer experience because you can share the webhook URL (endpoint) without creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. Make sure to read up on [security](#security) before using a webhook for calls that need to be authenticated.
 </Callout>
 
 <Callout type="info">
 See the full API reference for [`createWebhook()`](/docs/api-reference/workflow/create-webhook) for all available options.
 </Callout>
 
-### Creating Your First Webhook
+### Creating your first webhook
 
-Here's a simple webhook that receives HTTP requests. Like hooks, webhooks support the `using` keyword for automatic cleanup:
+Here's a webhook that receives HTTP requests. Like hooks, webhooks support the `using` keyword for automatic cleanup:
 
 ```typescript lineNumbers
 import { createWebhook } from "workflow";
@@ -255,13 +318,13 @@ export async function webhookWorkflow() {
 }
 ```
 
-The webhook will automatically respond with a `202 Accepted` status by default. External systems can simply make an HTTP request to the `webhook.url` to resume your workflow.
+The webhook will automatically respond with a `202 Accepted` status by default. External systems can make an HTTP request to the `webhook.url` to resume your workflow.
 
-### Sending Custom Responses
+### Sending custom responses
 
 Webhooks provide two ways to send custom HTTP responses: **static responses** and **dynamic responses**.
 
-#### Static Responses
+#### Static responses
 
 Use the `respondWith` option to provide a static response that will be sent automatically for every request:
 
@@ -290,7 +353,7 @@ async function processData(data: any) {
 }
 ```
 
-#### Dynamic Responses (Manual Mode)
+#### Dynamic responses (manual mode)
 
 For dynamic responses based on the request content, set `respondWith: "manual"` and call the `respondWith()` method on the request:
 
@@ -336,7 +399,7 @@ export async function webhookWithDynamicResponse() {
 When using `respondWith: "manual"`, the `respondWith()` method **must** be called from within a step function due to serialization requirements. This requirement may be removed in the future.
 </Callout>
 
-### Handling Multiple Webhook Requests
+### Handling multiple webhook requests
 
 Like hooks, webhooks support iteration:
 
@@ -376,7 +439,7 @@ export async function eventCollectorWorkflow() {
 }
 ```
 
-## Hooks vs. Webhooks: When to Use Each
+## Hooks vs. webhooks: when to use each
 
 | Feature | Hooks | Webhooks |
 |---------|-------|----------|
@@ -386,19 +449,107 @@ export async function eventCollectorWorkflow() {
 | **Use Case** | Custom integrations, type-safe payloads | HTTP webhooks, standard REST APIs |
 | **Resuming** | [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) | Automatic via HTTP, or [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) |
 
-**Use Hooks when:**
+**Use hooks when:**
 - You need full control over the payload structure
 - You're integrating with custom event sources
 - You want strong TypeScript typing with [`defineHook()`](/docs/api-reference/workflow/define-hook)
 
-**Use Webhooks when:**
+**Use webhooks when:**
 - You're receiving HTTP requests from external services
 - You need to send HTTP responses back to the caller
 - You want automatic URL routing without writing API handlers
 
-## Advanced Patterns
+## Security
+
+A hook token tells the runtime which hook a payload belongs to. It is not an authentication mechanism, and neither `resumeHook()` nor the webhook endpoint checks who is sending the payload.
+
+### Generated tokens are hard to guess, not secret
+
+When you don't pass a `token`, the SDK generates one inside the workflow function. Workflow code must produce the same values on every replay, so the generated token comes from the run's deterministic random number generator, the same one that backs [`Math.random()` and `crypto.randomUUID()`](/docs/api-reference/workflow-globals) in workflow functions. That generator is seeded from identifiers of the run, including the run ID, not from a secret key.
+
+A generated token is hard to guess without knowing the run, but the values it is derived from are not designed to be kept secret. Treat a generated token like an unlisted link, not like a credential.
+
+Custom tokens passed to `createHook({ token })` are usually built from domain data such as an order ID, so they are even easier to reconstruct. That is what makes them useful for routing, and it is why the route that resumes them must do its own authorization. If you can not perform your own authorization on the route that calls `resume` for any reason, and need to generate an unguessable token instead, generate it in a step where `crypto` is not seeded and pass it as `token`:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+async function generateToken() {
+  "use step";
+  // Steps run outside the workflow sandbox, so this uses the platform's
+  // cryptographic random source instead of the run's seed.
+  return crypto.randomUUID();
+}
+
+export async function approvalWorkflow() {
+  "use workflow";
+
+  const token = await generateToken(); // [!code highlight]
+  using hook = createHook<{ approved: boolean }>({ token }); // [!code highlight]
+
+  return (await hook).approved;
+}
+```
+
+The step result is recorded in the run's event log like any other step result. See [Encryption](/docs/how-it-works/encryption) to keep it encrypted at rest.
+
+### Webhook URLs
+
+[`createWebhook()`](/docs/api-reference/workflow/create-webhook) serves a public route at `/.well-known/workflow/v1/webhook/:token`, and matching the token is the only check it performs. Anyone who has the URL, or can compute its token, can resume the workflow with a request of their choosing. That is fine for low-stakes callbacks and prototypes. When a webhook request triggers something consequential, either:
+
+- Verify each request before acting on it, for example by checking the provider's HMAC signature in a step with [`respondWith: "manual"`](#dynamic-responses-manual-mode), and keep waiting for the next request when verification fails.
+- Use [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the caller before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), as shown below.
+
+### Authorize before calling `resumeHook()`
+
+`resumeHook()` delivers the payload to whichever hook owns the token. The route that calls it has to authenticate the caller and check that they are allowed to resume that specific hook. Knowing the token is not proof of either. One way is to record who may resume the hook in its `metadata`, then compare it to the signed-in user:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function expenseWorkflow(approverId: string) {
+  "use workflow";
+
+  using hook = createHook<{ approved: boolean }>({
+    metadata: { approverId }, // [!code highlight]
+  });
+
+  return (await hook).approved;
+}
+```
+
+```typescript lineNumbers
+import { getHookByToken, resumeHook } from "workflow/api";
+
+declare function getSession(request: Request): Promise<{ userId: string } | null>; // @setup
+
+export async function POST(request: Request) {
+  const session = await getSession(request); // [!code highlight]
+  if (!session) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const { token, approved } = await request.json();
+  const hook = await getHookByToken(token);
+  const metadata = (await hook.metadata) as { approverId?: string } | undefined;
+  if (metadata?.approverId !== session.userId) { // [!code highlight]
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  await resumeHook(token, { approved });
+  return Response.json({ success: true });
+}
+```
+
+Take the user identity from your authentication layer, never from the request body. Other examples in these docs omit authorization to stay short.
+
+### Randomness in workflow functions
+
+The same determinism applies to your own code. `Math.random()`, `crypto.randomUUID()`, and `crypto.getRandomValues()` in a workflow function return values derived from the run's seed, so they are predictable to anyone who knows it. Don't use them for secrets, passwords, one-time codes, or any value that must be unguessable. Generate those in a step, as in the token example above.
+
+## Advanced patterns
 
-### Type-Safe Hooks with `defineHook()`
+### Type-safe hooks with `defineHook()`
 
 The [`defineHook()`](/docs/api-reference/workflow/define-hook) helper provides type safety and runtime validation between creating and resuming hooks using [Standard Schema v1](https://standardschema.dev). Use any compliant validator like Zod or Valibot:
 
@@ -447,25 +598,25 @@ export async function POST(request: Request) {
 
 This pattern is especially valuable in larger applications where the workflow and API code are in separate files, providing both compile-time type safety and runtime validation.
 
-## Best Practices
+## Best practices
 
-### Token Design
+### Token design
 
-Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always use randomly generated tokens to prevent unauthorized access to public webhook endpoints.
+Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always generate their own unique tokens. Neither kind of token authorizes the sender; see [Security](#security).
 
 When using custom tokens with `createHook()`:
 
-- **Make them deterministic**: Base them on data the external system can reconstruct (like channel IDs, user IDs, etc.)
-- **Use namespacing**: Prefix tokens to avoid conflicts (e.g., `slack:${channelId}`, `github:${repoId}`)
-- **Include routing information**: Ensure the token contains enough information to identify the correct workflow instance
+- **Make them deterministic**: Base them on data the external system can reconstruct, such as channel IDs or user IDs.
+- **Use namespacing**: Prefix tokens to avoid conflicts, such as `slack:${channelId}` or `github:${repoId}`.
+- **Include routing information**: Ensure the token contains enough information to identify the correct workflow instance.
 
-### Response Handling in Webhooks
+### Response handling in webhooks
 
-- Use **static responses** (`respondWith: Response`) for simple acknowledgments
+- Use **static responses** (`respondWith: Response`) for acknowledgments
 - Use **manual mode** (`respondWith: "manual"`) when responses depend on request processing
 - Remember that `respondWith()` must be called from within a step function
 
-### Iterating Over Events
+### Iterating over events
 
 Both hooks and webhooks support iteration, making them perfect for long-running event loops:
 
@@ -484,7 +635,7 @@ for await (const event of hook) {
 
 This pattern allows a single workflow instance to handle multiple events over time, maintaining state between events.
 
-## Related Documentation
+## Related documentation
 
 - [Serialization](/docs/foundations/serialization) - Understanding what data can be passed through hooks
 - [`createHook()` API Reference](/docs/api-reference/workflow/create-hook)