workflow 5.0.0-beta.9 → 5.0.1

package/docs/api-reference/workflow-api/get-hook-by-token.mdx

@@ -5,14 +5,28 @@ type: reference
 summary: Use getHookByToken to look up a hook's metadata and associated workflow run before resuming it.
 prerequisites:
   - /docs/foundations/hooks
+related:
+  - /docs/foundations/idempotency
 ---
 
 Retrieves a hook by its unique token, returning the associated workflow run information and any metadata that was set when the hook was created. This function is useful for inspecting hook details before deciding whether to resume a workflow.
 
+When `experimental_minRetention` is set, this function continues to return the Hook after its workflow ends until retention ends. That Hook cannot be resumed. Use `getRun(hook.runId)` to inspect the finished run.
+
+When the Hook was created with [`experimental_force`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds) and took its token from another run, `hook.claimedFrom` names that run and its Hook. A lookup always follows the token to its current owner, so the same token returns the new Hook as soon as the takeover happens.
+
 <Callout type="warn">
 `getHookByToken` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="info">
+`hook.metadata` is a getter that returns a Promise, so `await` it to read the value. Hydrating metadata can add extra network round trips, so that work is deferred to first access and the lookup itself stays a single read. Awaiting it on a hook with no metadata resolves `undefined` and performs no extra work, and repeat reads are free.
+</Callout>
+
+<Callout type="info">
+Looking up a deterministic hook token is useful in hook-based idempotency flows, but it is only an advisory check. If no hook exists yet, another request can still start the same workflow before your `start()` call registers its hook. Use the lookup to avoid obvious duplicate starts, and handle the race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work. On a conflict it resolves with the run that owns the token, so the duplicate can route the caller to the active owner. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getHookByToken } from "workflow/api";
 
@@ -23,7 +37,7 @@ export async function POST(request: Request) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -40,14 +54,14 @@ Returns a `Promise<Hook>` that resolves to:
 
 <TSDoc
 definition={`
-import type { Hook } from "@workflow/world";
+import type { Hook } from "workflow/api";
 export default Hook;`}
 showSections={["returns"]}
 />
 
 ## Examples
 
-### Basic Hook Lookup
+### Basic hook lookup
 
 Retrieve hook information before resuming:
 
@@ -62,7 +76,7 @@ export async function POST(request: Request) {
     const hook = await getHookByToken(token); // [!code highlight]
 
     console.log("Resuming workflow run:", hook.runId);
-    console.log("Hook metadata:", hook.metadata);
+    console.log("Hook metadata:", await hook.metadata); // [!code highlight]
 
     // Then resume the hook with the payload
     await resumeHook(token, data);
@@ -77,22 +91,29 @@ export async function POST(request: Request) {
 }
 ```
 
-### Validating Hook Before Resume
+### Validating hook before resume
 
-Use `getHookByToken` to validate hook ownership or metadata before resuming:
+Use `getHookByToken` to validate hook ownership or metadata before resuming. Take the user's identity from your authentication layer, not from the request body. See [Hook and webhook security](/docs/foundations/hooks#security).
 
 ```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 { token, userId, data } = await request.json();
+  const session = await getSession(request);
+  if (!session) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { token, data } = await request.json();
 
   try {
     const hook = await getHookByToken(token); // [!code highlight]
-    const metadata = hook.metadata as { allowedUserId?: string } | undefined;
+    // `metadata` is a Promise, so awaiting it hydrates the stored value.
+    const metadata = (await hook.metadata) as { allowedUserId?: string } | undefined; // [!code highlight]
 
     // Validate that the hook metadata matches the user
-    if (metadata?.allowedUserId !== userId) {
+    if (metadata?.allowedUserId !== session.userId) {
       return Response.json(
         { error: "Unauthorized to resume this hook" },
         { status: 403 }
@@ -107,7 +128,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Checking Hook Environment
+### Checking hook environment
 
 Verify the hook belongs to the expected environment:
 
@@ -136,7 +157,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Logging Hook Information
+### Logging hook information
 
 Log hook details for debugging or auditing:
 
@@ -173,8 +194,9 @@ export async function POST(request: Request) {
 }
 ```
 
-## Related Functions
+## Related functions
 
-- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload.
-- [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resume a hook with a payload.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Create a hook in a workflow.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency): Deduplicate step side effects and workflow starts.

package/docs/api-reference/workflow-api/get-run.mdx

@@ -5,19 +5,25 @@ type: reference
 summary: Use getRun to check a workflow run's status and metadata without blocking on completion.
 prerequisites:
   - /docs/foundations/starting-workflows
+related:
+  - /docs/foundations/idempotency
 ---
 
-Retrieves the workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion, making it ideal for status checking and monitoring.
+Retrieves workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion.
 
 Use this function when you need to check workflow status, get timing information, or access workflow metadata without blocking on workflow completion.
 
+<Callout type="info">
+`getRun()` retrieves a run when you already have its `runId`. It does not look up runs by a business key. For retried requests that should route to one active workflow, use a deterministic hook token and [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). After a hook conflict, `HookConflictError.conflictingRunId` can be passed to `getRun()` to inspect, stream, or return the active owner. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getRun } from "workflow/api";
 
 const run = getRun("my-run-id");
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -41,7 +47,7 @@ showSections={["returns"]}
 
 #### WorkflowReadableStream
 
-`run.getReadable()` returns a `WorkflowReadableStream` — a standard `ReadableStream` extended with a `getTailIndex()` helper:
+`run.getReadable()` returns a `WorkflowReadableStream`, a standard `ReadableStream` extended with a `getTailIndex()` helper:
 
 <TSDoc
 definition={`
@@ -59,6 +65,16 @@ import type { WorkflowReadableStreamOptions } from "workflow/api";
 export default WorkflowReadableStreamOptions;`}
 />
 
+#### WorkflowRunWritableStreamOptions
+
+<TSDoc
+definition={`
+import type { WorkflowRunWritableStreamOptions } from "workflow/api";
+export default WorkflowRunWritableStreamOptions;`}
+/>
+
+Use `run.writable` for the default stream or `run.getWritable(options)` to configure it. See [Writing to another run's stream](/docs/foundations/streaming#writing-to-another-runs-stream) for lifecycle details.
+
 #### StopSleepOptions
 
 <TSDoc
@@ -77,7 +93,7 @@ export default StopSleepResult;`}
 
 ## Examples
 
-### Check if a Run Exists
+### Check if a run exists
 
 Use the `exists` getter to check whether a workflow run exists without throwing when the run is not found:
 
@@ -106,7 +122,7 @@ export async function GET(req: Request) {
 }
 ```
 
-### Basic Status Check
+### Basic status check
 
 Check the current status of a workflow run:
 
@@ -135,7 +151,7 @@ export async function GET(req: Request) {
 }
 ```
 
-### Wake Up a Sleeping Workflow
+### Wake up a sleeping workflow
 
 Interrupt pending `sleep()` calls to resume a workflow early. This is useful for testing workflows or building custom UIs that let users skip wait periods:
 
@@ -164,6 +180,25 @@ const { stoppedCount } = await run.wakeUp({
 });
 ```
 
-## Related Functions
+### Cancel a run
+
+Cancel a workflow run. You can pass an optional free-text `cancelReason` (up to 512 characters) that is recorded on the run's cancellation event and shown in the run detail view:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+export async function POST(req: Request) {
+  const { runId } = await req.json();
+  const run = getRun(runId);
+
+  await run.cancel({ cancelReason: "Superseded by a newer submission" }); // [!code highlight]
+
+  return Response.json({ cancelled: true });
+}
+```
+
+The options object is optional: `await run.cancel()` cancels the run without recording a reason.
+
+## Related functions
 
-- [`start()`](/docs/api-reference/workflow-api/start) - Start a new workflow and get its run ID.
+- [`start()`](/docs/api-reference/workflow-api/start): Start a new workflow and get its run ID.

package/docs/api-reference/workflow-api/index.mdx

@@ -1,16 +1,14 @@
 ---
 title: "workflow/api"
-description: Runtime functions to inspect runs, start workflows, and access world data.
+description: Runtime functions to inspect runs, start workflows, and manage hooks.
 type: overview
 summary: Explore runtime functions for starting workflows, inspecting runs, and managing hooks.
 ---
 
-API reference for runtime functions from the `workflow/api` package.
+The `workflow/api` package provides runtime functions to inspect runs, start new runs, and manage hooks.
 
 ## Functions
 
-The API package is for access and introspection of workflow data to inspect runs, start new runs, or access anything else directly accessible by the world.
-
 <Cards>
     <Card href="/docs/api-reference/workflow-api/start" title="start()">
         Start/enqueue a new workflow run.
@@ -27,10 +25,11 @@ The API package is for access and introspection of workflow data to inspect runs
     <Card href="/docs/api-reference/workflow-api/get-run" title="getRun()">
         Get workflow run status and metadata without waiting for completion.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/get-world" title="getWorld()">
-        Async: resolve the World instance for storage, queuing, and streaming backends.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world" title="World SDK">
-        Low-level API for inspecting runs, steps, events, hooks, streams, and queues.
+    <Card href="/docs/api-reference/workflow-api/register-lifecycle-hooks" title="registerLifecycleHooks()">
+        Observe run completions and failures with global handlers.
     </Card>
 </Cards>
+
+<Callout type="info">
+  Looking for `getWorld()` and the World SDK? They are exported from `workflow/runtime`. See the [`workflow/runtime` reference](/docs/api-reference/workflow-runtime).
+</Callout>

package/docs/api-reference/workflow-api/register-lifecycle-hooks.mdx

@@ -0,0 +1,87 @@
+---
+title: registerLifecycleHooks
+description: Register global handlers that observe workflow runs completing or failing.
+type: reference
+summary: Use registerLifecycleHooks to observe run completions and failures from one central place.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/lifecycle-hooks
+  - /docs/api-reference/workflow-api/get-run
+---
+
+Registers global workflow lifecycle handlers, invoked by the runtime on the compute that records a run's terminal transition. Use it for best-effort centralized reporting, such as forwarding failed runs to Sentry, without wrapping each workflow body.
+
+Register early in the process lifecycle (in Next.js, `instrumentation.ts`) so handlers exist before the first run finishes. See the [lifecycle hooks guide](/docs/observability/lifecycle-hooks) for semantics and a full Sentry example.
+
+```typescript title="instrumentation.ts" lineNumbers
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { registerLifecycleHooks } = await import("workflow/api");
+
+    registerLifecycleHooks({
+      async onRunCompleted({ run, workflowName }) {
+        console.log(`Run ${run.runId} (${workflowName}) completed`);
+      },
+      async onRunFailed({ run, workflowName, error }) {
+        console.error(
+          `Run ${run.runId} (${workflowName}) failed (${error.errorCode})`,
+          error.cause
+        );
+      },
+    });
+  }
+}
+```
+
+Keep the dynamic import inside the `NEXT_RUNTIME === "nodejs"` guard. Next.js also compiles `instrumentation.ts` for the Edge runtime. A top-level static import of `workflow/api` pulls Node.js-only dependencies into that compilation and breaks webpack Edge builds, even if the registration call is guarded.
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { registerLifecycleHooks } from "workflow/api";
+export default registerLifecycleHooks;`}
+showSections={["parameters"]}
+/>
+
+### Returns
+
+Returns a function that unregisters these hooks. Registrations are not deduplicated. Register each hook set once per process, and unregister the previous hooks before registering again during hot reload or module re-evaluation.
+
+## Handlers
+
+Both handlers receive a `workflowName` string and a lazily hydrated [`Run`](/docs/api-reference/workflow-api/get-run) instance. Use the `workflowName` parameter to filter without a backend read; `run.runId` also requires no read. Accessors such as `run.workflowName`, `run.status`, and `run.returnValue` still fetch from the backend when used. In particular, `workflowName` is a string, while `run.workflowName` is a `Promise<string>`. Lazy access defers those reads rather than eliminating them.
+
+### `onRunCompleted`
+
+Invoked when a workflow run completes successfully.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `params.run` | `Run` | The completed run. |
+| `params.workflowName` | `string` | The machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Available without a backend read. |
+
+### `onRunFailed`
+
+Invoked when a workflow run fails terminally (after any retries).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `params.run` | `Run` | The failed run. |
+| `params.workflowName` | `string` | The machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Available without a backend read. |
+| `params.error` | `WorkflowRunFailedError` | The persisted failure hydrated for reporting: `error.errorCode` carries the classification (e.g. `USER_ERROR`) and `error.cause` is the hydrated thrown value. |
+
+Unlike `run.returnValue`, `error.cause` defers readable stream I/O until consumption and revives abort signals as persisted snapshots without live subscriptions. Writable streams retain their normal forwarding pipe and lock-polling setup during hydration. If hydration fails, the cause is a generic `Error`, matching `run.returnValue`'s fallback. In `onRunFailed`, `run.returnValue` rejects because the run failed. Use `error.cause` to inspect or report the thrown value instead.
+
+The invocation's `waitUntil` scope includes background stream operations from the hydrated cause, even after a handler returns or throws. Close or release stream reader and writer locks when finished so that work can settle. Await other asynchronous reporting work in your handler to keep it in the same lifetime scope.
+
+## Behavior
+
+- Handlers run on the host (full Node.js), never inside the workflow VM. Calling `registerLifecycleHooks` from workflow code throws.
+- Handlers are fire-and-forget. They cannot delay or change the run's outcome, and the runtime logs and swallows a throwing handler. On Vercel, `waitUntil` keeps the invocation alive while handlers finish, subject to the invocation's duration limit. On other hosts, handlers run as detached work and may not complete if the host freezes or terminates the process after the response.
+- Delivery is best effort. Each registered handler is invoked at most once by the invocation that writes the terminal event. Callbacks are not retried if they throw or the process dies, so they may never run or may stop before completing. The [event log](/docs/how-it-works/event-sourcing) is the system of record.
+- Handlers fire only on the invocation that wrote the terminal event. Transitions recorded outside your app's compute (e.g. a run cancelled from the CLI or dashboard) do not fire handlers.
+- You can register multiple hook sets, and handlers run in registration order.

package/docs/api-reference/workflow-api/resume-hook.mdx

@@ -7,16 +7,25 @@ prerequisites:
   - /docs/foundations/hooks
 related:
   - /docs/api-reference/workflow-api/resume-webhook
+  - /docs/foundations/idempotency
 ---
 
 Resumes a workflow run by sending a payload to a hook identified by its token.
 
-It creates a `hook_received` event and re-triggers the workflow to continue execution.
+It durably writes the `hook_received` event and only then publishes a workflow wake. The call resolves only after both operations succeed, in that order.
+
+`resumeHook()` throws `HookNotFoundError` when no hook holds the token or when its `hook_received` write is refused because the hook was disposed or the run ended. See [durable hook resume](/docs/changelog/lazy-hook-resume).
+
+If `resumeHook()` throws any other error, the outcome is ambiguous only in dispatch, never in durability: the event may already be durable even though the workflow wake failed, and any later wake of the run delivers it. Calling `resumeHook()` again creates a new `resumeId` and can append a second `hook_received`. Callers that need at-most-once behavior across separate invocations must retain and deduplicate their own request key.
 
 <Callout type="warn">
 `resumeHook` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="warn">
+`resumeHook()` does not check who is calling it. Authenticate the caller and confirm they may resume this hook before calling it; knowing the token is not enough. The examples below omit that check for brevity. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 ```typescript lineNumbers
 import { resumeHook } from "workflow/api";
 
@@ -34,7 +43,7 @@ export async function POST(request: Request) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -47,18 +56,18 @@ showSections={["parameters"]}
 
 ### Returns
 
-Returns a `Promise<Hook>` that resolves to:
+Returns a `Promise<ResumedHook>`, a `Hook` (from `workflow/api`) extended with an optional `resilientResume` flag. Resolving means the payload is durably recorded as `hook_received` and the workflow wake was accepted. `resilientResume` is retained for source compatibility and is no longer set by any path. Resuming never reads the hook's metadata, so the resolved hook's `metadata` is a Promise that hydrates on first access, exactly as with [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token): `await hook.metadata` to read it. The resolved hook:
 
 <TSDoc
 definition={`
-import type { Hook } from "@workflow/world";
+import type { Hook } from "workflow/api";
 export default Hook;`}
 showSections={["returns"]}
 />
 
 ## Examples
 
-### Basic API Route
+### Basic API route
 
 Using `resumeHook` in a basic API route to resume a hook:
 
@@ -81,7 +90,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### With Type Safety
+### With type safety
 
 Defining a payload type and using `resumeHook` to resume a hook with type safety:
 
@@ -109,7 +118,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Server Action (Next.js)
+### Server action (Next.js)
 
 Using `resumeHook` in Next.js server actions to resume a hook:
 
@@ -128,7 +137,7 @@ export async function approveRequest(token: string, approved: boolean) {
 }
 ```
 
-### Webhook Handler
+### Webhook handler
 
 Using `resumeHook` in a generic webhook handler to resume a hook:
 
@@ -155,8 +164,64 @@ export async function POST(request: Request) {
 }
 ```
 
-## Related Functions
+### Resume or start
+
+A common endpoint shape is "resume or start": one route that resumes the active workflow run for a business key if one exists, or starts a new run otherwise. This comes up when the workflow uses a deterministic hook token as its idempotency key, for example, one active run per order or conversation.
+
+`resumeHook()` is the resume half of that flow. Try it first; if it throws `HookNotFoundError`, no active run owns the token yet, so start the workflow. One subtlety: `start()` returns before the new run executes and registers its hook, so you cannot resume immediately after starting. Retry the resume until the hook is registered: if you drop the payload and only start the workflow, the data from this request is lost.
+
+```typescript lineNumbers
+import { resumeHook, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+type OrderRequest = { confirmed: boolean };
+
+async function resumeWithRetry(token: string, payload: OrderRequest) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      return await resumeHook(token, payload); // [!code highlight]
+    } catch (error) {
+      if (!HookNotFoundError.is(error)) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  throw new Error("Workflow did not register its hook in time");
+}
+
+export async function POST(request: Request) {
+  const { orderId, confirmed } = await request.json();
+  const token = `order:${orderId}`;
+  const payload = { confirmed };
+
+  try {
+    // An active run already owns this token: resume it.
+    const hook = await resumeHook(token, payload); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
+
+  // No hook yet: start a new run, then retry the resume so this
+  // request's payload still reaches the workflow.
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  const resumed = await resumeWithRetry(token, payload);
+
+  // A concurrent request can win the race between `start()` and hook
+  // registration; the resume always reaches the actual active owner.
+  return Response.json({
+    runId: resumed.runId,
+    reused: resumed.runId !== run.runId,
+  });
+}
+```
+
+See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how the workflow claims the token with `hook.getConflict()` and how concurrent starts converge on one active owner.
+
+## Related functions
 
-- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) - Get hook details before resuming.
-- [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper.
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token): Get hook details before resuming.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Create a hook in a workflow.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency): Deduplicate step side effects and workflow starts.

package/docs/api-reference/workflow-api/resume-webhook.mdx

@@ -11,12 +11,16 @@ related:
 
 Resumes a workflow run by sending an HTTP `Request` to a webhook identified by its token.
 
-This function creates a `hook_received` event and re-triggers the workflow to continue execution. It's designed to be called from API routes or server actions that receive external HTTP requests.
+This function publishes a workflow invocation carrying the request; the runtime creates the `hook_received` event from it and continues execution. It's designed to be called from API routes or server actions that receive external HTTP requests.
 
 <Callout type="warn">
 `resumeWebhook` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="warn">
+The webhook token is the only authorization `resumeWebhook()` and the public webhook route perform. Verify requests before acting on them. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 ```typescript lineNumbers
 import { resumeWebhook } from "workflow/api";
 
@@ -37,7 +41,7 @@ export async function POST(request: Request) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -50,16 +54,18 @@ showSections={['parameters']}
 
 ### Returns
 
-Returns a `Promise<Response>` that resolves to:
+Returns a `Promise<Response>` that resolves to one of:
 
-- `Response`: The HTTP response from the workflow's `respondWith()` call
+- A `202 Accepted` response when the webhook was created in the default mode (no `respondWith` option).
+- The exact `Response` object configured via `createWebhook({ respondWith: new Response(...) })`.
+- The workflow's manual `Response` when the webhook was created with `createWebhook({ respondWith: "manual" })` and a step calls `request.respondWith(response)`.
 
-Throws an error if the webhook token is not found or invalid.
+Throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active webhook.
 
-## Usage Note
+## Usage note
 
 <Callout type="warn">
-In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a random webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
+In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
 
 For server-side hook resumption with deterministic tokens, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) with [`createHook()`](/docs/api-reference/workflow/create-hook) instead.
 </Callout>
@@ -81,14 +87,14 @@ export async function POST(request: Request) {
 
   try {
     const response = await resumeWebhook(token, request); // [!code highlight]
-    return response; // Returns the workflow's custom response
+    return response; // 202 Accepted, a configured static Response, or a manual workflow response
   } catch (error) {
     return new Response("Webhook not found", { status: 404 });
   }
 }
 ```
 
-## Related Functions
+## Related functions
 
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Create a webhook in a workflow
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with arbitrary payload