client.notify - Upstash Documentation

The notify method notifies workflows that are waiting for a specific event. Workflows paused at a context.waitForEvent step with the matching eventId will be resumed, and the provided eventData will be passed back to them.

Arguments

string

required

The identifier of the event to notify.

any

Data to deliver to the waiting workflow(s). This value will be returned in the eventData field of context.waitForEvent.

string

The workflow run ID to notify. When provided, enables lookback functionality - the notification will be stored and delivered even if notify is called before waitForEvent.This solves race conditions where notifications might be sent before a workflow reaches its wait step.

Response

NotifyResponse[]

A list of NotifyResponse objects, one for each workflow that was waiting on the event. An empty list means no workflow was waiting.

Hide child attributes

string

The ID of the notification message delivered to the workflow. This is unique to every notification.

string

Error message if delivering the notification to this waiter failed.

object

Show child attributes

string

required

URL to call upon notify

number

required

Unix timestamp for when the wait will time out

Record<string, string[]>

required

Headers sent in case of notify

string

URL to call upon timeout

unknown

Body used in timeout request

Record<string, string[]>

Headers sent in case of time out

Usage

Basic Notification

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

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

await client.notify({
  eventId: "my-event-id",
  eventData: "my-data", // data passed to the workflow run
});

Notification with Lookback

To prevent race conditions where a notification might arrive before the workflow reaches waitForEvent, you can provide a workflowRunId. This enables lookback - the notification will be stored and delivered even if sent before the wait step:

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

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

// Notify a specific workflow run with lookback support
await client.notify({
  eventId: "payment-processed",
  eventData: { amount: 100, status: "success" },
  workflowRunId: "wfr_abc123", // Enables lookback for this workflow run
});

This is particularly useful when you know which specific workflow run should receive the notification, such as after triggering a workflow and immediately sending it an event.

​Arguments

​Response

​Usage

​Basic Notification

​Notification with Lookback

Arguments

Response

Usage

Basic Notification

Notification with Lookback