Waiting for Events

You can use context.waitForEvent to pause a workflow until a specific event occurs and resume it with event data when the event is received.

​

context.waitForEvent

The waitForEvent method pauses the execution of a workflow and waits for an external event to occur, identified by an event ID. This is particularly useful in asynchronous workflows that rely on external systems to provide data or signals.

const { eventData, timeout } = await context.waitForEvent(
  "description of event",
  "event-id",
  {
    timeout: timeoutInSeconds
  }
);

Third parameter is the timeout. It is the maximum time (in seconds) to wait for the event. If the event doesn’t occur within this time, the workflow will proceed, and the timeout variable will be true.

Maximum timeout value is equal to the “Max Delay” value of your QStash plan. It’s 7 days for free users, 1 year for pay as you go users and unlimited for pro users.

​

client.notify

The notify method is used to notify a workflow that the expected event has occurred. It notifies all workflows waiting for the given eventId and provides the eventData to the waiting workflows, allowing them to resume execution.

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

await client.notify({
  eventId: "event-id",
  eventData: { my: "data" },
});

eventData provided in client.notify will be available in the result of context.waitForEvent as it is.

​

context.notify

You can also notify workflows in another workflow using the context.notify method.

const { notifyResponse } = await context.notify(
  "notify step", // notify step name
  "event-Id",    // event id
  { my: "data" } // event data
);