`defineHook()`

Creates a type-safe hook helper that ensures the payload type is consistent between hook creation and resumption.

This is a lightweight wrapper around createHook() and resumeHook() to avoid type mismatches.

We recommend using defineHook() over createHook() in production codebases for better type safety.

import { defineHook } from "workflow";

const nameHook = defineHook<{
  name: string;
}>();

export async function nameWorkflow() {
  "use workflow";

  const hook = nameHook.create();  
  const result = await hook; // Fully typed as { name: string }
  console.log('Name:', result.name);
}

API Signature

Parameters

This function does not accept any parameters.

Returns

Name	Type	Description
`create`	(options?: any) => Hook<T>	Creates a new hook with the defined payload type.
`resume`	(token: string, payload: T) => Promise<any>	Resumes a hook by sending a payload with the defined type.

Examples

Type-Safe Hook Definition

By defining the hook once with a specific payload type, you can reuse it in multiple workflows and API routes with automatic type safety.

import { defineHook } from "workflow";

// Define once with a specific payload type
const approvalHook = defineHook<{ 
  approved: boolean; 
  comment: string; 
}>(); 

// In your workflow
export async function workflowWithApproval() {
  "use workflow";

  const hook = approvalHook.create();
  const result = await hook; // Fully typed as { approved: boolean; comment: string }

  console.log('Approved:', result.approved);
  console.log('Comment:', result.comment);
}

Resuming with Type Safety

Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook.

// Use the same defined hook to resume
export async function POST(request: Request) {
  const { token, approved, comment } = await request.json();

  // Type-safe resumption - TypeScript ensures the payload matches
  const result = await approvalHook.resume(token, { 
    approved, 
    comment, 
  }); 

  if (!result) {
    return Response.json({ error: 'Hook not found' }, { status: 404 });
  }

  return Response.json({ success: true, runId: result.runId });
}

Customizing Tokens

Tokens are used to identify a specific hook and for resuming a hook. You can customize the token to be more specific to a use case.

const slackHook = defineHook<{ text: string; userId: string }>();

export async function slackBotWorkflow(channelId: string) {
  "use workflow";

  const hook = slackHook.create({
    token: `slack:${channelId}`, 
  });

  const message = await hook;
  console.log(`Message from ${message.userId}: ${message.text}`);
}

createHook() - Create a hook in a workflow.
resumeHook() - Resume a hook with a payload.