Create a low-level hook to resume workflows with arbitrary payloads.
Creates a low-level hook primitive that can be used to resume a workflow run with arbitrary payloads.
Hooks allow external systems to send data to a paused workflow without the HTTP-specific constraints of webhooks. They're identified by a token and can receive any serializable payload.
import { createHook } from "workflow"
export async function hookWorkflow() {
"use workflow";
// `using` automatically disposes the hook when it goes out of scope
using hook = createHook();
const result = await hook; // Suspends the workflow until the hook is resumed
}Parameters
| Name | Type | Description |
|---|---|---|
options | HookOptions | Configuration options for the hook. |
HookOptions
| Name | Type | Description |
|---|---|---|
token | string | Unique token that is used to associate with the hook.
When specifying an explicit token, the token should be constructed
with information that the dispatching side can reliably reconstruct
the token with the information it has available.
Deterministic tokens are intended for use with createHook() and
server-side resumeHook() only. For webhooks (createWebhook()),
tokens are always randomly generated to prevent unauthorized access
to the public webhook endpoint.
If not provided, a randomly generated token will be assigned. |
metadata | Serializable | Additional user-defined data to include with the hook payload. |
isWebhook | boolean | Whether this hook can be resumed via the public webhook endpoint.
When true, the hook can be triggered by sending an HTTP request to the
public /.well-known/workflow/v1/webhook/{token} URL. This is automatically
set when using createWebhook().
When false (the default), the hook can only be resumed server-side
via resumeHook(). |
Returns
Hook
| Name | Type | Description |
|---|---|---|
token | string | The token used to identify this hook. |
getConflict | () => Promise<Run<unknown> | null> | Returns a promise that resolves with the conflicting Run if
another active hook already owns this hook's token, or null once
the hook has been registered and is ready to receive payloads.
Calling createHook() alone does not register the hook — registration
only happens when the workflow suspends. Awaiting getConflict()
suspends the workflow to commit the hook registration, so it can be
used to claim the token (and detect token conflicts early) without
waiting for payload data.
When a conflict is detected, the resolved Run is the run that
currently owns the token. The workflow can decide how to handle the
duplicate in code: return or log conflict.runId, inspect
await conflict.status, await conflict.returnValue, or cancel the
owner with await conflict.cancel() and continue in the current run.
Note that awaiting the hook's payload (await hook) when the token is
already owned by another active hook still rejects with
HookConflictError. In the rare case where the conflicting run cannot
be identified (a hook_conflict event persisted by an old world that
did not record the owning run's ID), getConflict() also rejects with
HookConflictError rather than resolving with an incomplete value. |
dispose | () => void | Disposes the hook, releasing its token for reuse by other workflows.
After calling dispose(), the hook will no longer receive any events.
This is useful when you want to explicitly release a hook token before
the workflow completes, allowing another workflow to register a hook
with the same token. |
The returned Hook object also implements AsyncIterable<T>, which allows you to iterate over incoming payloads using for await...of syntax.
Use hook.getConflict() to check whether the hook token is already claimed by another active hook, without waiting for hook payload data. 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 registration, then resolves with null once hook_created is recorded, or with { runId } identifying the conflicting run if another active hook already owns the same token.
Basic Usage
When creating a hook, you can specify a payload type for automatic type safety:
import { createHook } from "workflow"
export async function approvalWorkflow() {
"use workflow";
using hook = createHook<{ approved: boolean; comment: string }>();
console.log("Send approval to token:", hook.token);
const result = await hook;
if (result.approved) {
console.log("Approved with comment:", result.comment);
}
}Customizing Tokens
Tokens are used to identify a specific hook. You can customize the token to be more specific to a use case.
import { createHook } from "workflow";
export async function slackBotWorkflow(channelId: string) {
"use workflow";
// Token constructed from channel ID
using hook = createHook<SlackMessage>({
token: `slack_messages:${channelId}`,
});
for await (const message of hook) {
if (message.text === "/stop") {
break;
}
await processMessage(message);
}
}Detecting Token Conflicts
Use hook.getConflict() when the workflow needs to claim a hook token before doing other work, but does not need a payload yet:
import { createHook } from "workflow";
declare function chargeOrder(orderId: string): Promise<void>; // @setup
async function processOrder(orderId: string) {
"use workflow";
using hook = createHook({
token: `order:${orderId}`
});
const conflict = await hook.getConflict();
if (conflict) {
// Another active workflow run already owns this token.
return { dedupedTo: conflict.runId };
}
await chargeOrder(orderId);
}Because createHook() alone does not suspend the workflow, awaiting hook.getConflict() is what actually suspends the run and commits the hook registration. It only waits for registration — to receive payload data from a future resumeHook() call, await the hook itself or iterate it with for await...of.
On a conflict, the resolved value is { runId } identifying the run that currently owns the token. To act on the owner — inspect its status, wait for its result, or cancel it — pass conflict.runId to getRun() inside a step. See Idempotency for these strategies in context.
Waiting for Multiple Payloads
You can also wait for multiple payloads by using the for await...of syntax.
import { createHook } from "workflow"
export async function collectHookWorkflow() {
"use workflow";
using hook = createHook<{ message: string; done?: boolean }>();
const payloads = [];
for await (const payload of hook) {
payloads.push(payload);
if (payload.done) break;
}
return payloads;
}Disposing Hooks Early
You can dispose a hook early to release its token for reuse by another workflow. This is useful for handoff patterns where one workflow needs to transfer a hook token to another workflow while still running.
import { createHook } from "workflow"
export async function handoffWorkflow(channelId: string) {
"use workflow";
const hook = createHook<{ message: string; handoff?: boolean }>({
token: `channel:${channelId}`
});
for await (const payload of hook) {
console.log("Received:", payload.message);
if (payload.handoff) {
hook.dispose(); // Release the token for another workflow
break;
}
}
// Continue with other work while another workflow uses the token
}After calling dispose(), the hook will no longer receive events and its token becomes available for other workflows to use.
Automatic Disposal with using
Hooks implement the TC39 Explicit Resource Management proposal, allowing automatic disposal with the using keyword:
import { createHook } from "workflow"
export async function scopedHookWorkflow(channelId: string) {
"use workflow";
{
using hook = createHook<{ message: string }>({
token: `channel:${channelId}`
});
const payload = await hook;
console.log("Received:", payload.message);
} // hook is automatically disposed here
// Token is now available for other workflows to use
console.log("Hook disposed, continuing with other work...");
}This is equivalent to manually calling dispose() but ensures the hook is always cleaned up, even if an error occurs.
defineHook()- Type-safe hook helperresumeHook()- Resume a hook with a payloadcreateWebhook()- Higher-level HTTP webhook abstraction