@workflow/core 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/api-reference/set-attributes.mdx

@@ -0,0 +1,61 @@
+---
+title: setAttributes
+description: Attach string metadata to workflow run for observability.
+type: reference
+summary: Use setAttributes inside a workflow or step function to set run attributes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/attributes
+  - /docs/api-reference/workflow/fatal-error
+---
+
+Attaches string metadata to the current workflow run.
+
+```typescript lineNumbers
+import { setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await setAttributes({
+    phase: "received",
+    orderId,
+  })
+}
+```
+
+## API signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { setAttributes } from "workflow";
+export default setAttributes;`}
+showSections={['parameters']}
+/>
+
+## Usage
+
+Call `setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
+
+Attribute values must be strings. Pass `undefined` to remove an attribute:
+
+```typescript lineNumbers
+import { setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await setAttributes({ staleKey: undefined })
+}
+```
+
+Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
+
+Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
+
+Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
+
+Native attributes require spec version 4 or later. Step-body storage errors throw from `setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid (such as exceeding the per-run attribute cap across multiple calls) fails the run with the validation error.

package/docs/api-reference/sleep.mdx

@@ -14,7 +14,7 @@ Suspends a workflow for a specified duration or until an end date without consum
 This is useful when you want to resume a workflow after some duration or date.
 
 <Callout>
-`sleep` is a *special* type of step function and should be called directly inside workflow functions.
+`sleep` is a built-in workflow runtime function (backed by a timer event in the event log, not a step) and should be called directly inside workflow functions.
 </Callout>
 
 ```typescript lineNumbers
@@ -26,7 +26,7 @@ async function testWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -39,7 +39,7 @@ showSections={['parameters']}
 
 ## Examples
 
-### Sleeping With a Duration
+### Sleeping with a duration
 
 You can specify a duration for `sleep` to suspend the workflow for a fixed amount of time.
 
@@ -52,7 +52,7 @@ async function testWorkflow() {
 }
 ```
 
-### Sleeping Until an End Date
+### Sleeping until an end date
 
 You can specify a future `Date` object for `sleep` to suspend the workflow until a specific date.
 

package/docs/foundations/cancellation.mdx

@@ -6,7 +6,6 @@ summary: Cancel in-flight work with AbortSignal or stop entire workflow runs.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
-  - /docs/foundations/common-patterns
   - /docs/foundations/hooks
   - /docs/how-it-works/cancellation
 ---
@@ -15,7 +14,7 @@ Workflow DevKit supports two cancellation mechanisms: **AbortSignal** for fine-g
 
 ## AbortSignal
 
-`AbortController` and `AbortSignal` work across workflow and step boundaries. Create an `AbortController` with `new AbortController()` in a workflow function, pass its signal to steps, and call `abort()` — using the standard [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) API you already know.
+`AbortController` and `AbortSignal` work across workflow and step boundaries. Create an `AbortController` with `new AbortController()` in a workflow function, pass its signal to steps, and call `abort()` using the standard [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) API.
 
 ```typescript lineNumbers
 import { sleep } from "workflow";
@@ -49,17 +48,17 @@ async function longRunningStep(signal: AbortSignal) {
 }
 ```
 
-No special imports, no wrapper functions — just the standard `AbortController` API.
+Use the standard `AbortController` API without special imports or wrapper functions.
 
 <Callout type="info">
-Cancellation is **cooperative**. Aborting a signal doesn't forcefully kill a step — it's up to the step's code to check `signal.aborted` or pass the signal to APIs like `fetch` that respect it. If a step ignores the signal, it runs to completion.
+Cancellation is **cooperative**. Aborting a signal doesn't forcefully kill a step. The step's code must check `signal.aborted` or pass the signal to APIs like `fetch` that respect it. If a step ignores the signal, it runs to completion.
 </Callout>
 
 <Callout type="info">
 To learn how `AbortController` works durably across workflow suspensions, replays, and step boundaries, see [How Cancellation Works](/docs/how-it-works/cancellation).
 </Callout>
 
-### Timeout with Cancellation
+### Timeout with cancellation
 
 Race a step against a timeout, and cancel the step if the timeout wins:
 
@@ -91,7 +90,7 @@ async function fetchUrl(url: string, signal: AbortSignal) {
 }
 ```
 
-### Cancelling Parallel Work
+### Cancelling parallel work
 
 When racing multiple steps, cancel the losers:
 
@@ -117,7 +116,7 @@ async function fetchUrl(url: string, signal: AbortSignal) {
 }
 ```
 
-### Passing Signal Through a Pipeline
+### Passing signal through a pipeline
 
 Pass the same signal to a chain of steps. Aborting cancels whichever step is currently running:
 
@@ -176,7 +175,7 @@ async function uploadData(data: ArrayBuffer, signal: AbortSignal) {
 }
 ```
 
-### Step-Initiated Abort
+### Step-initiated abort
 
 A step can receive the full `AbortController` and call `abort()` to cancel parallel work. This is useful for watchdog/monitor patterns where one step observes an external condition and cancels other in-flight steps:
 
@@ -221,7 +220,7 @@ async function monitorQuota(userId: string, controller: AbortController) {
 }
 ```
 
-### User-Triggered Cancellation with Hooks
+### User-triggered cancellation with hooks
 
 Combine hooks with abort controllers to let users cancel in-flight work from an external API:
 
@@ -267,23 +266,23 @@ export async function POST(request: Request) {
 }
 ```
 
-### How Steps Handle Abort
+### How steps handle abort
 
 When an `AbortSignal` is aborted, the behavior depends on how the step uses it:
 
-| Usage | Behavior on Abort |
+| Usage | Behavior on abort |
 |-------|-------------------|
-| `fetch(url, { signal })` | Request is cancelled, throws `AbortError` |
+| `fetch(url, { signal })` | Request is canceled, throws `AbortError` |
 | `signal.throwIfAborted()` | Throws the abort reason |
 | `signal.aborted` check | Returns `true`, step can exit gracefully |
 | `signal.addEventListener('abort', fn)` | Callback fires, step can clean up |
 | Ignored | Step runs to completion (abort is cooperative) |
 
-### Abort Errors Skip Retries
+### Abort errors skip retries
 
-When a step throws due to an abort (e.g., `fetch` throws `AbortError`, or `signal.throwIfAborted()` throws), the error is automatically wrapped in a `FatalError`. This means the step **skips retries** and the error bubbles up to the workflow immediately.
+When a step throws due to an abort (for example, `fetch` throws `AbortError`, or `signal.throwIfAborted()` throws), the runtime wraps the error in a `FatalError`. The step **skips retries**, and the error immediately bubbles up to the workflow.
 
-This is the correct behavior because an abort is an intentional cancellation — retrying the step would just result in another abort. You don't need to manually wrap abort errors in `FatalError`.
+An abort is an intentional cancellation, so retrying the step would result in another abort. You don't need to manually wrap abort errors in `FatalError`.
 
 ```typescript lineNumbers
 import { sleep } from "workflow";
@@ -300,7 +299,7 @@ export async function workflow() {
     if (result === null) controller.abort();
     return result;
   } catch (err) {
-    // AbortError arrives as FatalError — no retries attempted // [!code highlight]
+    // AbortError arrives as FatalError, with no retries attempted // [!code highlight]
     return { status: "cancelled" };
   }
 }
@@ -313,7 +312,7 @@ async function cancellableStep(signal: AbortSignal) {
 }
 ```
 
-### Passing AbortSignal as Workflow Input
+### Passing AbortSignal as workflow input
 
 You can pass an `AbortSignal` from external code into a workflow via `start()`:
 
@@ -330,15 +329,15 @@ export async function POST(request: Request) {
 }
 ```
 
-When the signal is serialized at the `start()` boundary, an event listener is attached to the external signal that writes the cancellation packet to the backing stream. This means the external `abort()` propagates into the workflow — but only while the originating process is still alive (same constraint as passing a `ReadableStream` as input).
+When the signal is serialized at the `start()` boundary, an event listener attaches to the external signal and writes the cancellation packet to the backing stream. The external `abort()` propagates into the workflow only while the originating process is still alive (the same constraint as passing a `ReadableStream` as input).
 
 <Callout type="info">
 For reliable external cancellation that works regardless of process lifetime, prefer the [User-Triggered Cancellation with Hooks](#user-triggered-cancellation-with-hooks) pattern. Hooks are durable and don't depend on the caller's process staying alive.
 </Callout>
 
-## Run Cancellation
+## Run cancellation
 
-Run cancellation stops an entire workflow at the next suspension point. Unlike `AbortSignal`, it is not cooperative — the workflow does not continue executing after cancellation.
+Run cancellation stops an entire workflow at the next suspension point. Unlike `AbortSignal`, it is not cooperative. The workflow does not continue executing after cancellation.
 
 ```typescript title="app/api/cancel-run/route.ts" lineNumbers
 import { getRun } from "workflow/api";
@@ -354,10 +353,10 @@ export async function POST(request: Request) {
 ```
 
 <Callout type="info">
-Calling `run.cancel()` is the same action as clicking the **Cancel** button on a run in the observability UI — both produce identical `run_cancelled` events in the event log.
+Calling `run.cancel()` is the same action as clicking the **Cancel** button on a run in the observability UI. Both produce identical `run_cancelled` events in the event log.
 </Callout>
 
-When a run is cancelled:
+When a run is canceled:
 - The workflow stops at its next suspension point (step call, hook await, or sleep)
 - A `run_cancelled` event is recorded in the [event log](/docs/how-it-works/event-sourcing)
 - All associated hooks are disposed and their tokens released
@@ -367,19 +366,19 @@ When a run is cancelled:
 Run cancellation does **not** automatically abort any outstanding `AbortSignal`s. Steps that are currently executing will run to completion. If you need in-flight cancellation of specific operations, use `AbortSignal`.
 </Callout>
 
-## AbortSignal vs. Run Cancellation
+## AbortSignal vs. run cancellation
 
 | | AbortSignal | Run Cancellation |
 |---|---|---|
 | **Scope** | Individual operations within a step | Entire workflow run |
 | **Triggered by** | Your code (`controller.abort()`) | External API (`run.cancel()`) |
-| **Cooperative** | Yes — steps must check the signal | No — workflow stops at the next suspension point |
+| **Cooperative** | Yes. Steps must check the signal | No. The workflow stops at the next suspension point |
 | **Granularity** | Can target specific steps or operations | All-or-nothing |
 | **In-flight steps** | Aborted immediately if using the signal | Run to completion |
 
 Use `AbortSignal` when you need fine-grained, in-flight cancellation of specific operations. Use run cancellation when you want to stop the entire workflow.
 
-## Best Practices
+## Best practices
 
 **Use `throwIfAborted()` before expensive work.** This throws the signal's abort reason if the signal is already aborted, preventing wasted compute:
 
@@ -449,12 +448,12 @@ export async function workflow() {
 }
 ```
 
-This is safe even if both steps have already completed — aborting a finished operation is a no-op.
+This is safe even if both steps have already completed because aborting a finished operation is a no-op.
 
-## Related Documentation
+## Related documentation
 
-- [How Cancellation Works](/docs/how-it-works/cancellation) — Hook and stream backing, serialization internals
-- [Serialization](/docs/foundations/serialization) — Understanding serializable types
-- [Common Patterns](/docs/foundations/common-patterns) — Timeout and race patterns
-- [Hooks](/docs/foundations/hooks) — Pausing workflows for external events
-- [Errors and Retries](/docs/foundations/errors-and-retries) — Handling step failures
+- [How Cancellation Works](/docs/how-it-works/cancellation): Hook and stream backing, serialization internals
+- [Serialization](/docs/foundations/serialization): Understanding serializable types
+- [Cookbook](/cookbook): Timeout, race, and other reliability patterns
+- [Hooks](/docs/foundations/hooks): Pausing workflows for external events
+- [Errors and Retries](/docs/foundations/errors-and-retries): Handling step failures

package/docs/foundations/errors-and-retries.mdx

@@ -1,6 +1,6 @@
 ---
 title: Errors & Retrying
-description: Customize retry behavior with FatalError and RetryableError for robust error handling.
+description: Customize retry behavior with FatalError and RetryableError.
 type: conceptual
 summary: Control how steps handle failures and customize retry behavior.
 prerequisites:
@@ -12,7 +12,7 @@ related:
 
 By default, errors thrown inside steps are retried. Additionally, Workflow SDK provides two new types of errors you can use to customize retries.
 
-## Default Retrying
+## Default retrying
 
 By default, steps retry up to 3 times on arbitrary errors. You can customize the number of retries by adding a `maxRetries` property to the step function.
 
@@ -42,9 +42,9 @@ Steps get enqueued immediately after a failure. Read on to see how this can be c
   more information.
 </Callout>
 
-## Intentional Errors
+## Intentional errors
 
-When your step needs to intentionally throw an error and skip retrying, simply throw a [`FatalError`](/docs/api-reference/workflow/fatal-error).
+When your step needs to intentionally throw an error and skip retrying, throw a [`FatalError`](/docs/api-reference/workflow/fatal-error).
 
 ```typescript lineNumbers
 import { FatalError } from "workflow";
@@ -67,7 +67,7 @@ async function callApi(endpoint: string) {
 }
 ```
 
-## Customize Retry Behavior
+## Customize retry behavior
 
 When you need to customize the delay on a retry, use [`RetryableError`](/docs/api-reference/workflow/retryable-error) and set the `retryAfter` property.
 
@@ -97,7 +97,7 @@ async function callApi(endpoint: string) {
 }
 ```
 
-## Advanced Example
+## Advanced example
 
 This final example combines everything we've learned, along with [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata).
 
@@ -139,7 +139,32 @@ callApi.maxRetries = 5; // Retry up to 5 times on failure (6 total attempts)
   step can run up to 4 times total (1 initial attempt + 3 retries).
 </Callout>
 
-## Error Codes
+## Serialization failures
+
+A step whose arguments or return value cannot be [serialized](/docs/foundations/serialization) fails like a step whose body threw a `FatalError`: the failure is deterministic, so it skips the retry loop, and a `try/catch` around the step call observes the `SerializationError`:
+
+```typescript lineNumbers
+async function someStep(input: unknown) {
+  "use step";
+  return input;
+}
+
+export async function myWorkflow(input: unknown) {
+  "use workflow";
+
+  try {
+    await someStep(input);
+  } catch (err) {
+    if ((err as Error).name === "SerializationError") {
+      // e.g. `Failed to serialize step arguments at path "..."`
+    }
+  }
+}
+```
+
+Uncaught, the run fails immediately with the `USER_ERROR` code, without retrying. See [serialization-failed](/docs/errors/serialization-failed) for common causes and fixes.
+
+## Error codes
 
 When a workflow run fails, the error includes an `errorCode` that classifies the failure, alongside the original thrown value (preserved as `cause`):
 
@@ -153,7 +178,7 @@ try {
   const result = await run.returnValue;
 } catch (err) {
   if (WorkflowRunFailedError.is(err)) {
-    console.log(err.errorCode); // "USER_ERROR", "RUNTIME_ERROR", or undefined
+    console.log(err.errorCode); // e.g. "USER_ERROR", "MAX_EVENTS_EXCEEDED", or undefined
     // `cause` is the original thrown value, hydrated through the workflow
     // serialization pipeline. It can be any thrown value, so check shape.
     if (err.cause instanceof Error) {
@@ -166,13 +191,19 @@ try {
 | Code | Meaning |
 | --- | --- |
 | `USER_ERROR` | An error thrown in your workflow or step code (including propagated step failures like `FatalError`) |
-| `RUNTIME_ERROR` | An internal runtime error such as a corrupted event log or missing data. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
+| `MAX_EVENTS_EXCEEDED` | The run reached the World's per-run event ceiling (25,000 on the Local and Vercel Worlds). Split unbounded loops into [child workflows](/cookbook/advanced/child-workflows); see [Limits](/docs/configuration/runtime-tuning#limits) |
+| `MAX_DELIVERIES_EXCEEDED` | The run exceeded the maximum number of queue deliveries |
+| `REPLAY_TIMEOUT` | A workflow replay exceeded the maximum allowed duration |
+| `REPLAY_DIVERGENCE` | A replay could not consume the event log deterministically, usually because of non-deterministic workflow code. |
+| `CORRUPTED_EVENT_LOG` | The event log cannot be replayed: it contains orphaned or mismatched events, or one of its stored payloads is no longer readable from the World's storage. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
+| `WORLD_CONTRACT_ERROR` | A World response violated the SDK contract; points at a World implementation bug |
+| `RUNTIME_ERROR` | An internal runtime error. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
 
 <Callout type="info">
-  The error code is also available on the run entity via the CLI (`npx workflow inspect runs <runId>`) in the `error.code` field, and as an OTEL span attribute (`workflow.error.code`) for observability.
+  The error code is also available on the run entity through the Workflow CLI (`npx workflow inspect runs <runId>`) in the `error.code` field, and as an OpenTelemetry span attribute (`workflow.error.code`) for observability.
 </Callout>
 
-## Rolling Back Failed Steps
+## Rolling back failed steps
 
 When a workflow fails partway through, it can leave the system in an inconsistent state.
 A common pattern to address this is "rollbacks": for each successful step, record a corresponding rollback action that can undo it.

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:
 
@@ -85,9 +85,38 @@ The key points:
 - You need the hook's `token` to resume it
 - 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,9 @@ 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
+## Understanding webhooks
 
-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:
+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 +251,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. This is convenient for prototypes 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.
 </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 +284,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 +319,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 +365,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 +405,7 @@ export async function eventCollectorWorkflow() {
 }
 ```
 
-## Hooks vs. Webhooks: When to Use Each
+## Hooks vs. webhooks: when to use each
 
 | Feature | Hooks | Webhooks |
 |---------|-------|----------|
@@ -386,19 +415,19 @@ 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
+## 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 +476,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. A generated token is not trivial to guess, but it is not a strong security contract either, so anyone who obtains the URL can invoke an unintended webhook resumption. To prevent unauthenticated run resumptions entirely, prefer a **hook** over the **webhook** convenience and implement your own authentication on the route that calls `resumeHook()`.
 
 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 +513,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)