workflow 5.0.0-beta.9 → 5.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -23
- package/dist/api-workflow.d.ts +3 -1
- package/dist/api-workflow.d.ts.map +1 -1
- package/dist/api-workflow.js +2 -1
- package/dist/api.d.ts +5 -4
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +6 -7
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -1
- package/dist/internal/builtins.d.ts +4 -4
- package/dist/internal/builtins.js +6 -6
- package/dist/internal/errors.d.ts +1 -1
- package/dist/internal/errors.d.ts.map +1 -1
- package/dist/internal/errors.js +2 -2
- package/dist/nest-builder.d.ts +2 -0
- package/dist/nest-builder.d.ts.map +1 -0
- package/dist/nest-builder.js +2 -0
- package/dist/nest-vercel-builder.d.ts +2 -0
- package/dist/nest-vercel-builder.d.ts.map +1 -0
- package/dist/nest-vercel-builder.js +2 -0
- package/dist/runtime.d.ts +2 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +4 -1
- package/docs/advanced/dynamic-workflows.mdx +224 -0
- package/docs/ai/chat-session-modeling.mdx +176 -422
- package/docs/ai/defining-tools.mdx +6 -7
- package/docs/ai/human-in-the-loop.mdx +11 -11
- package/docs/ai/index.mdx +67 -72
- package/docs/ai/message-queueing.mdx +71 -110
- package/docs/ai/meta.json +1 -0
- package/docs/ai/resumable-streams.mdx +40 -28
- package/docs/ai/sleep-and-delays.mdx +10 -10
- package/docs/ai/streaming-updates-from-tools.mdx +6 -6
- package/docs/api-reference/index.mdx +25 -1
- package/docs/api-reference/meta.json +8 -0
- package/docs/api-reference/vitest/index.mdx +68 -15
- package/docs/api-reference/workflow/create-hook.mdx +166 -10
- package/docs/api-reference/workflow/create-webhook.mdx +16 -15
- package/docs/api-reference/workflow/define-hook.mdx +37 -33
- package/docs/api-reference/workflow/fatal-error.mdx +30 -8
- package/docs/api-reference/workflow/fetch.mdx +14 -10
- package/docs/api-reference/workflow/get-step-metadata.mdx +2 -2
- package/docs/api-reference/workflow/get-workflow-metadata.mdx +3 -3
- package/docs/api-reference/workflow/get-writable.mdx +7 -7
- package/docs/api-reference/workflow/index.mdx +3 -3
- package/docs/api-reference/workflow/retryable-error.mdx +1 -1
- package/docs/api-reference/workflow/set-attributes.mdx +63 -0
- package/docs/api-reference/workflow/sleep.mdx +4 -4
- package/docs/api-reference/workflow-ai/durable-agent.mdx +63 -101
- package/docs/api-reference/workflow-ai/index.mdx +5 -5
- package/docs/api-reference/workflow-ai/workflow-chat-transport.mdx +67 -24
- package/docs/api-reference/workflow-api/get-hook-by-token.mdx +28 -12
- package/docs/api-reference/workflow-api/get-run.mdx +43 -8
- package/docs/api-reference/workflow-api/index.mdx +8 -9
- package/docs/api-reference/workflow-api/register-lifecycle-hooks.mdx +87 -0
- package/docs/api-reference/workflow-api/resume-hook.mdx +73 -12
- package/docs/api-reference/workflow-api/resume-webhook.mdx +11 -9
- package/docs/api-reference/workflow-api/start.mdx +107 -12
- package/docs/api-reference/workflow-astro/index.mdx +18 -0
- package/docs/api-reference/workflow-astro/meta.json +4 -0
- package/docs/api-reference/workflow-astro/workflow.mdx +45 -0
- package/docs/api-reference/workflow-errors/entity-conflict-error.mdx +4 -4
- package/docs/api-reference/workflow-errors/hook-conflict-error.mdx +60 -0
- package/docs/api-reference/workflow-errors/hook-force-claimed-error.mdx +70 -0
- package/docs/api-reference/workflow-errors/hook-not-found-error.mdx +8 -8
- package/docs/api-reference/workflow-errors/index.mdx +91 -0
- package/docs/api-reference/workflow-errors/meta.json +7 -0
- package/docs/api-reference/workflow-errors/precondition-failed-error.mdx +68 -0
- package/docs/api-reference/workflow-errors/run-expired-error.mdx +2 -2
- package/docs/api-reference/workflow-errors/run-not-supported-error.mdx +58 -0
- package/docs/api-reference/workflow-errors/step-not-registered-error.mdx +5 -5
- package/docs/api-reference/workflow-errors/throttle-error.mdx +2 -2
- package/docs/api-reference/workflow-errors/too-early-error.mdx +2 -2
- package/docs/api-reference/workflow-errors/workflow-error.mdx +52 -0
- package/docs/api-reference/workflow-errors/workflow-not-registered-error.mdx +5 -6
- package/docs/api-reference/workflow-errors/workflow-run-cancelled-error.mdx +13 -6
- package/docs/api-reference/workflow-errors/workflow-run-failed-error.mdx +12 -5
- package/docs/api-reference/workflow-errors/workflow-run-not-completed-error.mdx +58 -0
- package/docs/api-reference/workflow-errors/workflow-run-not-found-error.mdx +4 -4
- package/docs/api-reference/workflow-errors/workflow-runtime-error.mdx +58 -0
- package/docs/api-reference/workflow-errors/workflow-world-error.mdx +8 -8
- package/docs/api-reference/workflow-globals.mdx +15 -11
- package/docs/api-reference/workflow-nest/configure-workflow-controller.mdx +37 -0
- package/docs/api-reference/workflow-nest/index.mdx +31 -0
- package/docs/api-reference/workflow-nest/meta.json +9 -0
- package/docs/api-reference/workflow-nest/nest-local-builder.mdx +64 -0
- package/docs/api-reference/workflow-nest/workflow-controller.mdx +46 -0
- package/docs/api-reference/workflow-nest/workflow-module.mdx +134 -0
- package/docs/api-reference/workflow-next/with-workflow.mdx +39 -17
- package/docs/api-reference/workflow-nitro/index.mdx +60 -0
- package/docs/api-reference/workflow-nuxt/index.mdx +48 -0
- package/docs/api-reference/workflow-observability/hydrate-data.mdx +35 -0
- package/docs/api-reference/workflow-observability/hydrate-resource-io.mdx +62 -0
- package/docs/api-reference/workflow-observability/index.mdx +62 -0
- package/docs/api-reference/workflow-observability/meta.json +11 -0
- package/docs/api-reference/workflow-observability/observability-revivers.mdx +50 -0
- package/docs/api-reference/workflow-observability/parse-class-name.mdx +41 -0
- package/docs/api-reference/workflow-observability/parse-step-name.mdx +40 -0
- package/docs/api-reference/workflow-observability/parse-workflow-name.mdx +55 -0
- package/docs/api-reference/workflow-runtime/create-world.mdx +39 -0
- package/docs/api-reference/workflow-runtime/get-world-handlers.mdx +44 -0
- package/docs/api-reference/{workflow-api → workflow-runtime}/get-world.mdx +11 -14
- package/docs/api-reference/workflow-runtime/health-check.mdx +51 -0
- package/docs/api-reference/workflow-runtime/index.mdx +41 -0
- package/docs/api-reference/workflow-runtime/meta.json +12 -0
- package/docs/api-reference/workflow-runtime/set-world.mdx +51 -0
- package/docs/api-reference/workflow-runtime/workflow-entrypoint.mdx +43 -0
- package/docs/api-reference/workflow-runtime/world/analytics.mdx +315 -0
- package/docs/api-reference/workflow-runtime/world/index.mdx +60 -0
- package/docs/api-reference/workflow-runtime/world/meta.json +4 -0
- package/docs/api-reference/workflow-runtime/world/queue.mdx +88 -0
- package/docs/api-reference/{workflow-api → workflow-runtime}/world/storage.mdx +104 -35
- package/docs/api-reference/{workflow-api → workflow-runtime}/world/streams.mdx +8 -8
- package/docs/api-reference/workflow-serde/index.mdx +1 -2
- package/docs/api-reference/workflow-serde/workflow-deserialize.mdx +3 -4
- package/docs/api-reference/workflow-serde/workflow-serialize.mdx +8 -8
- package/docs/api-reference/workflow-sveltekit/index.mdx +18 -0
- package/docs/api-reference/workflow-sveltekit/meta.json +4 -0
- package/docs/api-reference/workflow-sveltekit/workflow-plugin.mdx +42 -0
- package/docs/api-reference/workflow-vite/index.mdx +18 -0
- package/docs/api-reference/workflow-vite/meta.json +4 -0
- package/docs/api-reference/workflow-vite/workflow.mdx +48 -0
- package/docs/changelog/attributes-mvp.mdx +53 -41
- package/docs/changelog/batched-event-writes.mdx +79 -0
- package/docs/changelog/eager-processing.mdx +110 -436
- package/docs/changelog/index.mdx +4 -2
- package/docs/changelog/lazy-event-creation.md +127 -0
- package/docs/changelog/lazy-hook-resume.mdx +78 -0
- package/docs/changelog/meta.json +11 -1
- package/docs/changelog/resilient-resume.mdx +32 -0
- package/docs/changelog/resilient-start.mdx +33 -285
- package/docs/changelog/step-message-ownership.mdx +360 -0
- package/docs/changelog/turbo-mode.md +87 -0
- package/docs/comparisons/index.mdx +66 -0
- package/docs/comparisons/meta.json +11 -0
- package/docs/comparisons/workflow-sdk-vs-aws-agentcore.mdx +55 -0
- package/docs/comparisons/workflow-sdk-vs-aws-step-functions.mdx +111 -0
- package/docs/comparisons/workflow-sdk-vs-cloudflare-workflows.mdx +71 -0
- package/docs/comparisons/workflow-sdk-vs-inngest.mdx +102 -0
- package/docs/comparisons/workflow-sdk-vs-temporal.mdx +123 -0
- package/docs/comparisons/workflow-sdk-vs-trigger-dev.mdx +104 -0
- package/docs/configuration/build-and-diagnostics.mdx +79 -0
- package/docs/configuration/cli-and-web-ui.mdx +241 -0
- package/docs/configuration/framework-options.mdx +165 -0
- package/docs/configuration/index.mdx +32 -0
- package/docs/configuration/meta.json +12 -0
- package/docs/configuration/runtime-tuning.mdx +399 -0
- package/docs/configuration/worlds.mdx +315 -0
- package/docs/cookbook/advanced/child-workflows.mdx +33 -25
- package/docs/cookbook/advanced/publishing-libraries.mdx +65 -56
- package/docs/cookbook/advanced/serializable-steps.mdx +48 -68
- package/docs/cookbook/advanced/upgrading-workflows.mdx +35 -31
- package/docs/cookbook/agent-patterns/agent-cancellation.mdx +78 -60
- package/docs/cookbook/agent-patterns/durable-agent.mdx +23 -135
- package/docs/cookbook/agent-patterns/human-in-the-loop.mdx +180 -195
- package/docs/cookbook/common-patterns/batching.mdx +20 -14
- package/docs/cookbook/common-patterns/idempotency.mdx +41 -53
- package/docs/cookbook/common-patterns/rate-limiting.mdx +8 -4
- package/docs/cookbook/common-patterns/saga.mdx +23 -19
- package/docs/cookbook/common-patterns/scheduling.mdx +30 -22
- package/docs/cookbook/common-patterns/sequential-and-parallel.mdx +29 -25
- package/docs/cookbook/common-patterns/timeouts.mdx +26 -21
- package/docs/cookbook/common-patterns/webhooks.mdx +10 -6
- package/docs/cookbook/common-patterns/workflow-composition.mdx +27 -17
- package/docs/cookbook/index.mdx +22 -22
- package/docs/cookbook/integrations/ai-sdk.mdx +63 -48
- package/docs/cookbook/integrations/chat-sdk.mdx +46 -33
- package/docs/cookbook/integrations/sandbox.mdx +58 -45
- package/docs/deploying.mdx +106 -0
- package/docs/errors/abort-signal-timeout-in-workflow.mdx +16 -12
- package/docs/errors/corrupted-event-log.mdx +39 -18
- package/docs/errors/deployment-mismatch.mdx +71 -0
- package/docs/errors/fetch-in-workflow.mdx +15 -14
- package/docs/errors/hook-conflict.mdx +38 -11
- package/docs/errors/hook-force-claimed.mdx +96 -0
- package/docs/errors/index.mdx +24 -37
- package/docs/errors/node-js-module-in-workflow.mdx +9 -5
- package/docs/errors/replay-divergence.mdx +27 -0
- package/docs/errors/run-expired.mdx +85 -0
- package/docs/errors/runtime-decryption-failed.mdx +77 -0
- package/docs/errors/serialization-failed.mdx +44 -12
- package/docs/errors/start-invalid-workflow-function.mdx +9 -5
- package/docs/errors/step-executed-multiple-times.mdx +23 -0
- package/docs/errors/step-not-registered.mdx +6 -6
- package/docs/errors/timeout-in-workflow.mdx +12 -8
- package/docs/errors/webhook-invalid-respond-with-value.mdx +18 -18
- package/docs/errors/webhook-response-not-sent.mdx +20 -16
- package/docs/errors/workflow-not-registered.mdx +5 -5
- package/docs/foundations/cancellation.mdx +31 -32
- package/docs/foundations/errors-and-retries.mdx +54 -11
- package/docs/foundations/hooks.mdx +98 -35
- package/docs/foundations/idempotency.mdx +267 -12
- package/docs/foundations/index.mdx +1 -26
- package/docs/foundations/serialization.mdx +22 -22
- package/docs/foundations/starting-workflows.mdx +104 -30
- package/docs/foundations/streaming.mdx +108 -60
- package/docs/foundations/versioning.mdx +4 -4
- package/docs/foundations/workflows-and-steps.mdx +9 -9
- package/docs/getting-started/astro.mdx +22 -18
- package/docs/getting-started/express.mdx +15 -11
- package/docs/getting-started/fastify.mdx +15 -11
- package/docs/getting-started/hono.mdx +15 -11
- package/docs/getting-started/index.mdx +10 -3
- package/docs/getting-started/meta.json +3 -1
- package/docs/getting-started/nestjs.mdx +264 -21
- package/docs/getting-started/next.mdx +18 -14
- package/docs/getting-started/nitro.mdx +22 -18
- package/docs/getting-started/nuxt.mdx +15 -11
- package/docs/getting-started/python.mdx +190 -41
- package/docs/getting-started/react-router/index.mdx +33 -0
- package/docs/getting-started/react-router/meta.json +5 -0
- package/docs/getting-started/react-router/v7.mdx +237 -0
- package/docs/getting-started/react-router/v8.mdx +232 -0
- package/docs/getting-started/sveltekit.mdx +20 -16
- package/docs/getting-started/tanstack-start.mdx +17 -13
- package/docs/getting-started/vite.mdx +15 -11
- package/docs/how-it-works/cancellation.mdx +63 -63
- package/docs/how-it-works/code-transform.mdx +82 -66
- package/docs/how-it-works/encryption.mdx +30 -26
- package/docs/how-it-works/event-sourcing.mdx +132 -35
- package/docs/how-it-works/framework-integrations.mdx +96 -337
- package/docs/how-it-works/understanding-directives.mdx +22 -22
- package/docs/internal/index.mdx +6 -4
- package/docs/internal/meta.json +6 -1
- package/docs/internal/nitro-native-build.mdx +38 -0
- package/docs/internal/nitro-web-ui.mdx +24 -0
- package/docs/internal/serializable-abort-controller.mdx +7 -7
- package/docs/meta.json +4 -2
- package/docs/observability/attributes.mdx +91 -21
- package/docs/observability/index.mdx +29 -15
- package/docs/observability/lifecycle-hooks.mdx +95 -0
- package/docs/observability/meta.json +1 -1
- package/docs/observability/retention.mdx +95 -0
- package/docs/observability/tracing.mdx +124 -0
- package/docs/testing/index.mdx +120 -38
- package/docs/testing/server-based.mdx +10 -10
- package/docs/whats-new.mdx +190 -0
- package/docs/worlds/building-a-world.mdx +538 -0
- package/docs/worlds/local.mdx +129 -0
- package/docs/worlds/meta.json +10 -0
- package/docs/worlds/postgres.mdx +424 -0
- package/docs/worlds/upgrading-to-v5.mdx +162 -0
- package/docs/worlds/vercel.mdx +345 -0
- package/package.json +17 -14
- package/docs/api-reference/workflow/experimental-set-attributes.mdx +0 -63
- package/docs/api-reference/workflow-api/world/index.mdx +0 -58
- package/docs/api-reference/workflow-api/world/meta.json +0 -4
- package/docs/api-reference/workflow-api/world/observability.mdx +0 -164
- package/docs/api-reference/workflow-api/world/queue.mdx +0 -86
- package/docs/deploying/building-a-world.mdx +0 -251
- package/docs/deploying/index.mdx +0 -95
- package/docs/deploying/meta.json +0 -4
- package/docs/deploying/world/local-world.mdx +0 -84
- package/docs/deploying/world/meta.json +0 -4
- package/docs/deploying/world/postgres-world.mdx +0 -224
- package/docs/deploying/world/vercel-world.mdx +0 -181
- package/docs/migration-guides/index.mdx +0 -34
- package/docs/migration-guides/meta.json +0 -9
- package/docs/migration-guides/migrating-from-aws-step-functions.mdx +0 -358
- package/docs/migration-guides/migrating-from-inngest.mdx +0 -304
- package/docs/migration-guides/migrating-from-temporal.mdx +0 -313
- package/docs/migration-guides/migrating-from-trigger-dev.mdx +0 -328
|
@@ -5,14 +5,28 @@ type: reference
|
|
|
5
5
|
summary: Use getHookByToken to look up a hook's metadata and associated workflow run before resuming it.
|
|
6
6
|
prerequisites:
|
|
7
7
|
- /docs/foundations/hooks
|
|
8
|
+
related:
|
|
9
|
+
- /docs/foundations/idempotency
|
|
8
10
|
---
|
|
9
11
|
|
|
10
12
|
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.
|
|
11
13
|
|
|
14
|
+
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.
|
|
15
|
+
|
|
16
|
+
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.
|
|
17
|
+
|
|
12
18
|
<Callout type="warn">
|
|
13
19
|
`getHookByToken` is a runtime function that must be called from outside a workflow function.
|
|
14
20
|
</Callout>
|
|
15
21
|
|
|
22
|
+
<Callout type="info">
|
|
23
|
+
`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.
|
|
24
|
+
</Callout>
|
|
25
|
+
|
|
26
|
+
<Callout type="info">
|
|
27
|
+
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).
|
|
28
|
+
</Callout>
|
|
29
|
+
|
|
16
30
|
```typescript lineNumbers
|
|
17
31
|
import { getHookByToken } from "workflow/api";
|
|
18
32
|
|
|
@@ -23,7 +37,7 @@ export async function POST(request: Request) {
|
|
|
23
37
|
}
|
|
24
38
|
```
|
|
25
39
|
|
|
26
|
-
## API
|
|
40
|
+
## API signature
|
|
27
41
|
|
|
28
42
|
### Parameters
|
|
29
43
|
|
|
@@ -40,14 +54,14 @@ Returns a `Promise<Hook>` that resolves to:
|
|
|
40
54
|
|
|
41
55
|
<TSDoc
|
|
42
56
|
definition={`
|
|
43
|
-
import type { Hook } from "
|
|
57
|
+
import type { Hook } from "workflow/api";
|
|
44
58
|
export default Hook;`}
|
|
45
59
|
showSections={["returns"]}
|
|
46
60
|
/>
|
|
47
61
|
|
|
48
62
|
## Examples
|
|
49
63
|
|
|
50
|
-
### Basic
|
|
64
|
+
### Basic hook lookup
|
|
51
65
|
|
|
52
66
|
Retrieve hook information before resuming:
|
|
53
67
|
|
|
@@ -62,7 +76,7 @@ export async function POST(request: Request) {
|
|
|
62
76
|
const hook = await getHookByToken(token); // [!code highlight]
|
|
63
77
|
|
|
64
78
|
console.log("Resuming workflow run:", hook.runId);
|
|
65
|
-
console.log("Hook metadata:", hook.metadata);
|
|
79
|
+
console.log("Hook metadata:", await hook.metadata); // [!code highlight]
|
|
66
80
|
|
|
67
81
|
// Then resume the hook with the payload
|
|
68
82
|
await resumeHook(token, data);
|
|
@@ -77,7 +91,7 @@ export async function POST(request: Request) {
|
|
|
77
91
|
}
|
|
78
92
|
```
|
|
79
93
|
|
|
80
|
-
### Validating
|
|
94
|
+
### Validating hook before resume
|
|
81
95
|
|
|
82
96
|
Use `getHookByToken` to validate hook ownership or metadata before resuming:
|
|
83
97
|
|
|
@@ -89,7 +103,8 @@ export async function POST(request: Request) {
|
|
|
89
103
|
|
|
90
104
|
try {
|
|
91
105
|
const hook = await getHookByToken(token); // [!code highlight]
|
|
92
|
-
|
|
106
|
+
// `metadata` is a Promise, so awaiting it hydrates the stored value.
|
|
107
|
+
const metadata = (await hook.metadata) as { allowedUserId?: string } | undefined; // [!code highlight]
|
|
93
108
|
|
|
94
109
|
// Validate that the hook metadata matches the user
|
|
95
110
|
if (metadata?.allowedUserId !== userId) {
|
|
@@ -107,7 +122,7 @@ export async function POST(request: Request) {
|
|
|
107
122
|
}
|
|
108
123
|
```
|
|
109
124
|
|
|
110
|
-
### Checking
|
|
125
|
+
### Checking hook environment
|
|
111
126
|
|
|
112
127
|
Verify the hook belongs to the expected environment:
|
|
113
128
|
|
|
@@ -136,7 +151,7 @@ export async function POST(request: Request) {
|
|
|
136
151
|
}
|
|
137
152
|
```
|
|
138
153
|
|
|
139
|
-
### Logging
|
|
154
|
+
### Logging hook information
|
|
140
155
|
|
|
141
156
|
Log hook details for debugging or auditing:
|
|
142
157
|
|
|
@@ -173,8 +188,9 @@ export async function POST(request: Request) {
|
|
|
173
188
|
}
|
|
174
189
|
```
|
|
175
190
|
|
|
176
|
-
## Related
|
|
191
|
+
## Related functions
|
|
177
192
|
|
|
178
|
-
- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook)
|
|
179
|
-
- [`createHook()`](/docs/api-reference/workflow/create-hook)
|
|
180
|
-
- [`defineHook()`](/docs/api-reference/workflow/define-hook)
|
|
193
|
+
- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resume a hook with a payload.
|
|
194
|
+
- [`createHook()`](/docs/api-reference/workflow/create-hook): Create a hook in a workflow.
|
|
195
|
+
- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
|
|
196
|
+
- [Idempotency](/docs/foundations/idempotency): Deduplicate step side effects and workflow starts.
|
|
@@ -5,19 +5,25 @@ type: reference
|
|
|
5
5
|
summary: Use getRun to check a workflow run's status and metadata without blocking on completion.
|
|
6
6
|
prerequisites:
|
|
7
7
|
- /docs/foundations/starting-workflows
|
|
8
|
+
related:
|
|
9
|
+
- /docs/foundations/idempotency
|
|
8
10
|
---
|
|
9
11
|
|
|
10
|
-
Retrieves
|
|
12
|
+
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.
|
|
11
13
|
|
|
12
14
|
Use this function when you need to check workflow status, get timing information, or access workflow metadata without blocking on workflow completion.
|
|
13
15
|
|
|
16
|
+
<Callout type="info">
|
|
17
|
+
`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).
|
|
18
|
+
</Callout>
|
|
19
|
+
|
|
14
20
|
```typescript lineNumbers
|
|
15
21
|
import { getRun } from "workflow/api";
|
|
16
22
|
|
|
17
23
|
const run = getRun("my-run-id");
|
|
18
24
|
```
|
|
19
25
|
|
|
20
|
-
## API
|
|
26
|
+
## API signature
|
|
21
27
|
|
|
22
28
|
### Parameters
|
|
23
29
|
|
|
@@ -41,7 +47,7 @@ showSections={["returns"]}
|
|
|
41
47
|
|
|
42
48
|
#### WorkflowReadableStream
|
|
43
49
|
|
|
44
|
-
`run.getReadable()` returns a `WorkflowReadableStream
|
|
50
|
+
`run.getReadable()` returns a `WorkflowReadableStream`, a standard `ReadableStream` extended with a `getTailIndex()` helper:
|
|
45
51
|
|
|
46
52
|
<TSDoc
|
|
47
53
|
definition={`
|
|
@@ -59,6 +65,16 @@ import type { WorkflowReadableStreamOptions } from "workflow/api";
|
|
|
59
65
|
export default WorkflowReadableStreamOptions;`}
|
|
60
66
|
/>
|
|
61
67
|
|
|
68
|
+
#### WorkflowRunWritableStreamOptions
|
|
69
|
+
|
|
70
|
+
<TSDoc
|
|
71
|
+
definition={`
|
|
72
|
+
import type { WorkflowRunWritableStreamOptions } from "workflow/api";
|
|
73
|
+
export default WorkflowRunWritableStreamOptions;`}
|
|
74
|
+
/>
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
62
78
|
#### StopSleepOptions
|
|
63
79
|
|
|
64
80
|
<TSDoc
|
|
@@ -77,7 +93,7 @@ export default StopSleepResult;`}
|
|
|
77
93
|
|
|
78
94
|
## Examples
|
|
79
95
|
|
|
80
|
-
### Check if a
|
|
96
|
+
### Check if a run exists
|
|
81
97
|
|
|
82
98
|
Use the `exists` getter to check whether a workflow run exists without throwing when the run is not found:
|
|
83
99
|
|
|
@@ -106,7 +122,7 @@ export async function GET(req: Request) {
|
|
|
106
122
|
}
|
|
107
123
|
```
|
|
108
124
|
|
|
109
|
-
### Basic
|
|
125
|
+
### Basic status check
|
|
110
126
|
|
|
111
127
|
Check the current status of a workflow run:
|
|
112
128
|
|
|
@@ -135,7 +151,7 @@ export async function GET(req: Request) {
|
|
|
135
151
|
}
|
|
136
152
|
```
|
|
137
153
|
|
|
138
|
-
### Wake
|
|
154
|
+
### Wake up a sleeping workflow
|
|
139
155
|
|
|
140
156
|
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:
|
|
141
157
|
|
|
@@ -164,6 +180,25 @@ const { stoppedCount } = await run.wakeUp({
|
|
|
164
180
|
});
|
|
165
181
|
```
|
|
166
182
|
|
|
167
|
-
|
|
183
|
+
### Cancel a run
|
|
184
|
+
|
|
185
|
+
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:
|
|
186
|
+
|
|
187
|
+
```typescript lineNumbers
|
|
188
|
+
import { getRun } from "workflow/api";
|
|
189
|
+
|
|
190
|
+
export async function POST(req: Request) {
|
|
191
|
+
const { runId } = await req.json();
|
|
192
|
+
const run = getRun(runId);
|
|
193
|
+
|
|
194
|
+
await run.cancel({ cancelReason: "Superseded by a newer submission" }); // [!code highlight]
|
|
195
|
+
|
|
196
|
+
return Response.json({ cancelled: true });
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
The options object is optional: `await run.cancel()` cancels the run without recording a reason.
|
|
201
|
+
|
|
202
|
+
## Related functions
|
|
168
203
|
|
|
169
|
-
- [`start()`](/docs/api-reference/workflow-api/start)
|
|
204
|
+
- [`start()`](/docs/api-reference/workflow-api/start): Start a new workflow and get its run ID.
|
|
@@ -1,16 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "workflow/api"
|
|
3
|
-
description: Runtime functions to inspect runs, start workflows, and
|
|
3
|
+
description: Runtime functions to inspect runs, start workflows, and manage hooks.
|
|
4
4
|
type: overview
|
|
5
5
|
summary: Explore runtime functions for starting workflows, inspecting runs, and managing hooks.
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The `workflow/api` package provides runtime functions to inspect runs, start new runs, and manage hooks.
|
|
9
9
|
|
|
10
10
|
## Functions
|
|
11
11
|
|
|
12
|
-
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.
|
|
13
|
-
|
|
14
12
|
<Cards>
|
|
15
13
|
<Card href="/docs/api-reference/workflow-api/start" title="start()">
|
|
16
14
|
Start/enqueue a new workflow run.
|
|
@@ -27,10 +25,11 @@ The API package is for access and introspection of workflow data to inspect runs
|
|
|
27
25
|
<Card href="/docs/api-reference/workflow-api/get-run" title="getRun()">
|
|
28
26
|
Get workflow run status and metadata without waiting for completion.
|
|
29
27
|
</Card>
|
|
30
|
-
<Card href="/docs/api-reference/workflow-api/
|
|
31
|
-
|
|
32
|
-
</Card>
|
|
33
|
-
<Card href="/docs/api-reference/workflow-api/world" title="World SDK">
|
|
34
|
-
Low-level API for inspecting runs, steps, events, hooks, streams, and queues.
|
|
28
|
+
<Card href="/docs/api-reference/workflow-api/register-lifecycle-hooks" title="registerLifecycleHooks()">
|
|
29
|
+
Observe run completions and failures with global handlers.
|
|
35
30
|
</Card>
|
|
36
31
|
</Cards>
|
|
32
|
+
|
|
33
|
+
<Callout type="info">
|
|
34
|
+
Looking for `getWorld()` and the World SDK? They are exported from `workflow/runtime`. See the [`workflow/runtime` reference](/docs/api-reference/workflow-runtime).
|
|
35
|
+
</Callout>
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: registerLifecycleHooks
|
|
3
|
+
description: Register global handlers that observe workflow runs completing or failing.
|
|
4
|
+
type: reference
|
|
5
|
+
summary: Use registerLifecycleHooks to observe run completions and failures from one central place.
|
|
6
|
+
prerequisites:
|
|
7
|
+
- /docs/foundations/workflows-and-steps
|
|
8
|
+
related:
|
|
9
|
+
- /docs/observability/lifecycle-hooks
|
|
10
|
+
- /docs/api-reference/workflow-api/get-run
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
```typescript title="instrumentation.ts" lineNumbers
|
|
18
|
+
export async function register() {
|
|
19
|
+
if (process.env.NEXT_RUNTIME === "nodejs") {
|
|
20
|
+
const { registerLifecycleHooks } = await import("workflow/api");
|
|
21
|
+
|
|
22
|
+
registerLifecycleHooks({
|
|
23
|
+
async onRunCompleted({ run, workflowName }) {
|
|
24
|
+
console.log(`Run ${run.runId} (${workflowName}) completed`);
|
|
25
|
+
},
|
|
26
|
+
async onRunFailed({ run, workflowName, error }) {
|
|
27
|
+
console.error(
|
|
28
|
+
`Run ${run.runId} (${workflowName}) failed (${error.errorCode})`,
|
|
29
|
+
error.cause
|
|
30
|
+
);
|
|
31
|
+
},
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
## API Signature
|
|
40
|
+
|
|
41
|
+
### Parameters
|
|
42
|
+
|
|
43
|
+
<TSDoc
|
|
44
|
+
definition={`
|
|
45
|
+
import { registerLifecycleHooks } from "workflow/api";
|
|
46
|
+
export default registerLifecycleHooks;`}
|
|
47
|
+
showSections={["parameters"]}
|
|
48
|
+
/>
|
|
49
|
+
|
|
50
|
+
### Returns
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
## Handlers
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
### `onRunCompleted`
|
|
59
|
+
|
|
60
|
+
Invoked when a workflow run completes successfully.
|
|
61
|
+
|
|
62
|
+
| Parameter | Type | Description |
|
|
63
|
+
| --- | --- | --- |
|
|
64
|
+
| `params.run` | `Run` | The completed run. |
|
|
65
|
+
| `params.workflowName` | `string` | The machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Available without a backend read. |
|
|
66
|
+
|
|
67
|
+
### `onRunFailed`
|
|
68
|
+
|
|
69
|
+
Invoked when a workflow run fails terminally (after any retries).
|
|
70
|
+
|
|
71
|
+
| Parameter | Type | Description |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| `params.run` | `Run` | The failed run. |
|
|
74
|
+
| `params.workflowName` | `string` | The machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Available without a backend read. |
|
|
75
|
+
| `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. |
|
|
76
|
+
|
|
77
|
+
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.
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
## Behavior
|
|
82
|
+
|
|
83
|
+
- Handlers run on the host (full Node.js), never inside the workflow VM. Calling `registerLifecycleHooks` from workflow code throws.
|
|
84
|
+
- 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.
|
|
85
|
+
- 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.
|
|
86
|
+
- 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.
|
|
87
|
+
- You can register multiple hook sets, and handlers run in registration order.
|
|
@@ -7,11 +7,16 @@ prerequisites:
|
|
|
7
7
|
- /docs/foundations/hooks
|
|
8
8
|
related:
|
|
9
9
|
- /docs/api-reference/workflow-api/resume-webhook
|
|
10
|
+
- /docs/foundations/idempotency
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
Resumes a workflow run by sending a payload to a hook identified by its token.
|
|
13
14
|
|
|
14
|
-
It
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
`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).
|
|
18
|
+
|
|
19
|
+
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.
|
|
15
20
|
|
|
16
21
|
<Callout type="warn">
|
|
17
22
|
`resumeHook` is a runtime function that must be called from outside a workflow function.
|
|
@@ -34,7 +39,7 @@ export async function POST(request: Request) {
|
|
|
34
39
|
}
|
|
35
40
|
```
|
|
36
41
|
|
|
37
|
-
## API
|
|
42
|
+
## API signature
|
|
38
43
|
|
|
39
44
|
### Parameters
|
|
40
45
|
|
|
@@ -47,18 +52,18 @@ showSections={["parameters"]}
|
|
|
47
52
|
|
|
48
53
|
### Returns
|
|
49
54
|
|
|
50
|
-
Returns a `Promise<Hook
|
|
55
|
+
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:
|
|
51
56
|
|
|
52
57
|
<TSDoc
|
|
53
58
|
definition={`
|
|
54
|
-
import type { Hook } from "
|
|
59
|
+
import type { Hook } from "workflow/api";
|
|
55
60
|
export default Hook;`}
|
|
56
61
|
showSections={["returns"]}
|
|
57
62
|
/>
|
|
58
63
|
|
|
59
64
|
## Examples
|
|
60
65
|
|
|
61
|
-
### Basic API
|
|
66
|
+
### Basic API route
|
|
62
67
|
|
|
63
68
|
Using `resumeHook` in a basic API route to resume a hook:
|
|
64
69
|
|
|
@@ -81,7 +86,7 @@ export async function POST(request: Request) {
|
|
|
81
86
|
}
|
|
82
87
|
```
|
|
83
88
|
|
|
84
|
-
### With
|
|
89
|
+
### With type safety
|
|
85
90
|
|
|
86
91
|
Defining a payload type and using `resumeHook` to resume a hook with type safety:
|
|
87
92
|
|
|
@@ -109,7 +114,7 @@ export async function POST(request: Request) {
|
|
|
109
114
|
}
|
|
110
115
|
```
|
|
111
116
|
|
|
112
|
-
### Server
|
|
117
|
+
### Server action (Next.js)
|
|
113
118
|
|
|
114
119
|
Using `resumeHook` in Next.js server actions to resume a hook:
|
|
115
120
|
|
|
@@ -128,7 +133,7 @@ export async function approveRequest(token: string, approved: boolean) {
|
|
|
128
133
|
}
|
|
129
134
|
```
|
|
130
135
|
|
|
131
|
-
### Webhook
|
|
136
|
+
### Webhook handler
|
|
132
137
|
|
|
133
138
|
Using `resumeHook` in a generic webhook handler to resume a hook:
|
|
134
139
|
|
|
@@ -155,8 +160,64 @@ export async function POST(request: Request) {
|
|
|
155
160
|
}
|
|
156
161
|
```
|
|
157
162
|
|
|
158
|
-
|
|
163
|
+
### Resume or start
|
|
164
|
+
|
|
165
|
+
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.
|
|
166
|
+
|
|
167
|
+
`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.
|
|
168
|
+
|
|
169
|
+
```typescript lineNumbers
|
|
170
|
+
import { resumeHook, start } from "workflow/api";
|
|
171
|
+
import { HookNotFoundError } from "workflow/errors";
|
|
172
|
+
import { processOrder } from "./workflows/process-order";
|
|
173
|
+
|
|
174
|
+
type OrderRequest = { confirmed: boolean };
|
|
175
|
+
|
|
176
|
+
async function resumeWithRetry(token: string, payload: OrderRequest) {
|
|
177
|
+
for (let attempt = 0; attempt < 5; attempt++) {
|
|
178
|
+
try {
|
|
179
|
+
return await resumeHook(token, payload); // [!code highlight]
|
|
180
|
+
} catch (error) {
|
|
181
|
+
if (!HookNotFoundError.is(error)) throw error;
|
|
182
|
+
await new Promise((resolve) => setTimeout(resolve, 100));
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
throw new Error("Workflow did not register its hook in time");
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
export async function POST(request: Request) {
|
|
190
|
+
const { orderId, confirmed } = await request.json();
|
|
191
|
+
const token = `order:${orderId}`;
|
|
192
|
+
const payload = { confirmed };
|
|
193
|
+
|
|
194
|
+
try {
|
|
195
|
+
// An active run already owns this token: resume it.
|
|
196
|
+
const hook = await resumeHook(token, payload); // [!code highlight]
|
|
197
|
+
return Response.json({ runId: hook.runId, reused: true });
|
|
198
|
+
} catch (error) {
|
|
199
|
+
if (!HookNotFoundError.is(error)) throw error;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
// No hook yet: start a new run, then retry the resume so this
|
|
203
|
+
// request's payload still reaches the workflow.
|
|
204
|
+
const run = await start(processOrder, [orderId]); // [!code highlight]
|
|
205
|
+
const resumed = await resumeWithRetry(token, payload);
|
|
206
|
+
|
|
207
|
+
// A concurrent request can win the race between `start()` and hook
|
|
208
|
+
// registration; the resume always reaches the actual active owner.
|
|
209
|
+
return Response.json({
|
|
210
|
+
runId: resumed.runId,
|
|
211
|
+
reused: resumed.runId !== run.runId,
|
|
212
|
+
});
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
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.
|
|
217
|
+
|
|
218
|
+
## Related functions
|
|
159
219
|
|
|
160
|
-
- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token)
|
|
161
|
-
- [`createHook()`](/docs/api-reference/workflow/create-hook)
|
|
162
|
-
- [`defineHook()`](/docs/api-reference/workflow/define-hook)
|
|
220
|
+
- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token): Get hook details before resuming.
|
|
221
|
+
- [`createHook()`](/docs/api-reference/workflow/create-hook): Create a hook in a workflow.
|
|
222
|
+
- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
|
|
223
|
+
- [Idempotency](/docs/foundations/idempotency): Deduplicate step side effects and workflow starts.
|
|
@@ -11,7 +11,7 @@ related:
|
|
|
11
11
|
|
|
12
12
|
Resumes a workflow run by sending an HTTP `Request` to a webhook identified by its token.
|
|
13
13
|
|
|
14
|
-
This function
|
|
14
|
+
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.
|
|
15
15
|
|
|
16
16
|
<Callout type="warn">
|
|
17
17
|
`resumeWebhook` is a runtime function that must be called from outside a workflow function.
|
|
@@ -37,7 +37,7 @@ export async function POST(request: Request) {
|
|
|
37
37
|
}
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
## API
|
|
40
|
+
## API signature
|
|
41
41
|
|
|
42
42
|
### Parameters
|
|
43
43
|
|
|
@@ -50,16 +50,18 @@ showSections={['parameters']}
|
|
|
50
50
|
|
|
51
51
|
### Returns
|
|
52
52
|
|
|
53
|
-
Returns a `Promise<Response>` that resolves to:
|
|
53
|
+
Returns a `Promise<Response>` that resolves to one of:
|
|
54
54
|
|
|
55
|
-
- `
|
|
55
|
+
- A `202 Accepted` response when the webhook was created in the default mode (no `respondWith` option).
|
|
56
|
+
- The exact `Response` object configured via `createWebhook({ respondWith: new Response(...) })`.
|
|
57
|
+
- The workflow's manual `Response` when the webhook was created with `createWebhook({ respondWith: "manual" })` and a step calls `request.respondWith(response)`.
|
|
56
58
|
|
|
57
|
-
Throws
|
|
59
|
+
Throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active webhook.
|
|
58
60
|
|
|
59
|
-
## Usage
|
|
61
|
+
## Usage note
|
|
60
62
|
|
|
61
63
|
<Callout type="warn">
|
|
62
|
-
In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a
|
|
64
|
+
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.
|
|
63
65
|
|
|
64
66
|
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.
|
|
65
67
|
</Callout>
|
|
@@ -81,14 +83,14 @@ export async function POST(request: Request) {
|
|
|
81
83
|
|
|
82
84
|
try {
|
|
83
85
|
const response = await resumeWebhook(token, request); // [!code highlight]
|
|
84
|
-
return response; //
|
|
86
|
+
return response; // 202 Accepted, a configured static Response, or a manual workflow response
|
|
85
87
|
} catch (error) {
|
|
86
88
|
return new Response("Webhook not found", { status: 404 });
|
|
87
89
|
}
|
|
88
90
|
}
|
|
89
91
|
```
|
|
90
92
|
|
|
91
|
-
## Related
|
|
93
|
+
## Related functions
|
|
92
94
|
|
|
93
95
|
- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Create a webhook in a workflow
|
|
94
96
|
- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with arbitrary payload
|