world.hooks

Look up workflow hooks by ID or token for webhook resume flows and metadata inspection.

The world.hooks interface provides access to workflow hook data. Hooks are pause points in workflows that wait for external input. Use this interface to look up hooks by ID or token, inspect metadata, and build admin UIs for pending approvals.

Import

import { getWorld } from "workflow/runtime";

const world = getWorld();
const hooks = world.hooks;

Methods

get()

Retrieve a hook by its ID.

const hook = await world.hooks.get(hookId);

Parameters:

Parameter	Type	Description
`hookId`	`string`	The hook ID
`params`	`object`	Optional parameters

Returns: Hook

getByToken()

Look up a hook by its token. Useful in webhook resume flows where you receive a token in the callback URL.

const hook = await world.hooks.getByToken(token);

Parameters:

Parameter	Type	Description
`token`	`string`	The hook token
`params`	`object`	Optional parameters

Returns: Hook

list()

List hooks with cursor pagination.

const result = await world.hooks.list({ 
  pagination: { cursor },
});

Parameters:

Parameter	Type	Description
`params.pagination.cursor`	`string`	Cursor for the next page

Returns: { data: Hook[], cursor?: string }

Types

Hook

Field	Type	Description
`runId`	`string`	Parent workflow run ID
`hookId`	`string`	Unique hook identifier
`token`	`string`	Hook token for resuming
`ownerId`	`string`	Owner (team/user) ID
`projectId`	`string`	Project ID
`environment`	`string`	Deployment environment
`metadata`	`object`	Custom metadata attached to the hook
`isWebhook`	`boolean`	Whether this is a webhook-style hook

Examples

Look Up Hook by ID

import { getWorld } from "workflow/runtime";

export async function GET(req: Request) {
  const url = new URL(req.url);
  const hookId = url.searchParams.get("hookId");

  if (!hookId) {
    return Response.json({ error: "hookId required" }, { status: 400 });
  }

  const world = getWorld();
  const hook = await world.hooks.get(hookId); 

  return Response.json({
    hookId: hook.hookId,
    runId: hook.runId,
    token: hook.token,
    metadata: hook.metadata,
  });
}

Look Up Hook by Token for Webhook Resume

When you receive a webhook callback with a token, look up the hook to inspect metadata before resuming:

import { getWorld } from "workflow/runtime";

export async function POST(req: Request) {
  const { token } = await req.json();

  const world = getWorld();
  const hook = await world.hooks.getByToken(token); 

  // Inspect hook metadata before deciding to resume
  console.log(hook.runId, hook.metadata); 

  return Response.json({
    runId: hook.runId,
    hookId: hook.hookId,
    metadata: hook.metadata,
  });
}

List All Hooks for Pending Approvals Dashboard

import { getWorld } from "workflow/runtime";

export async function GET(req: Request) {
  const url = new URL(req.url);
  const cursor = url.searchParams.get("cursor") ?? undefined;

  const world = getWorld();
  const hooks = await world.hooks.list({ 
    pagination: { cursor },
  }); 

  return Response.json(hooks);
}

resumeHook() — Resume a workflow by sending a payload to a hook
resumeWebhook() — Resume a workflow via webhook
getHookByToken() — Higher-level API for hook lookup
Hooks — Core concepts for hooks and pause points

world.hooks

On this page