context.waitForEvent - Upstash Documentation

context.waitForEvent pauses workflow execution until a given event occurs or a timeout is reached.

Default timeout value is 7 days.

Arguments#

stepIdstringrequired#

A unique identifier for the step.

eventIdstringrequired#

A unique identifier for the event to wait on.

optionsobject#

Show properties

timeoutnumber|string#

The maximum time to wait before continuing execution.

String format: Human‑readable duration (e.g., "10s", "2h", "1d").
Number format: Duration in seconds (e.g., 60, 3600).

Defaults to 7d (7 days).

Response#

eventDataTEventData#

The data passed in when the event is triggered via notify(). Its type can be set with the generic parameter, e.g. context.waitForEvent<{ approved: boolean }>(...). Defaults to unknown.

timeoutboolean#

true if execution resumed because the timeout elapsed, false if resumed due to the event being received.

Usage#

import { serve } from "@upstash/workflow/nextjs";export const { POST } = serve<{ topic: string }>(async (context) => {  const request = context.requestPayload;  const {    eventData,    timeout,  } = await context.waitForEvent("wait for some event", "my-event-id", {    timeout: "1000s", // 1000 second timeout  });});