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#

eventIdstringrequired#

The identifier of the event to notify.

eventDataany#

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

workflowRunIdstring#

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#

responseNotifyResponse[]#

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

Show properties

messageIdstring#

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

errorstring#

Error message if delivering the notification to this waiter failed.

Waiterobject#

Show properties

urlstringrequired#

URL to call upon notify

deadlinenumberrequired#

Unix timestamp for when the wait will time out

headersRecord<string, string[]>required#

Headers sent in case of notify

timeoutUrlstring#

URL to call upon timeout

timeoutBodyunknown#

Body used in timeout request

timeoutHeadersRecord<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 supportawait 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.