context.notify - Upstash Documentation

context.notify() notifies workflows that are waiting for a specific event, passing along an optional payload.

It is typically used in combination with context.waitForEvent.

Arguments#

stepNamestring#

A unique identifier for the step.

eventIdstring#

The identifier of the event to notify. Must match the eventId used in context.waitForEvent.

eventDataany#

Data to deliver to the waiting workflow(s). This value will be returned in eventData from the corresponding waitForEvent call.

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#

context.notify() returns an object containing the notified event and the list of workflows that were notified.

eventIdstring#

The event ID that was notified.

eventDataany#

The event data sent with the notification.

notifyResponseNotifyResponse[]#

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 { serve } from "@upstash/workflow/nextjs";export const { POST } = serve<{ topic: string }>(async (context) => {  const payload = context.requestPayload;  const {    notifyResponse, // result of notify, which is a list of notified waiters  } = await context.notify("notify step", "my-event-Id", payload);});

Notification with Lookback#

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

import { serve } from "@upstash/workflow/nextjs";export const { POST } = serve<{ orderId: string }>(async (context) => {  const { orderId } = context.requestPayload;  // Process payment  await context.run("process-payment", async () => {    return processPayment(orderId);  });  // Notify a specific workflow run with lookback support  const {    notifyResponse,  } = await context.notify(    "notify payment complete",    "payment-processed",    { orderId, status: "success" },    "wfr_order_processor_123" // Enables lookback for this workflow run  );});