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

string

A unique identifier for the step.

string

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

any

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

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

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

string

The event ID that was notified.

any

The event data sent with the notification.

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 { 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
  );
});

​Arguments

​Response

​Usage

​Basic Notification

​Notification with Lookback

Arguments

Response

Usage

Basic Notification

Notification with Lookback