Notify Workflow Run Event

Notify an event to a specific workflow run’s waiters.

This endpoint sends an event notification to waiters within a specific workflow run. Unlike the general notify endpoint, this uses a “safe notify” mechanism that guarantees delivery even if no waiter is currently active.

Safe Notify Behavior:

• If a waiter is currently active, it receives the notification immediately
• If no waiter is active, the notification is saved in the database
• When a waiter becomes active later, it will consume the saved notification
• This ensures events are never lost due to timing issues

Workflow calls (with Upstash-Workflow-RunId header) are exempt from daily quota limits.

POST /v2/notify/{workflowRunId}/{eventId}

Notify Workflow Run Event

cURL

curl --request POST \
  --url https://qstash.upstash.io/v2/notify/{workflowRunId}/{eventId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

201

{
  "waiter": {
    "url": "<string>",
    "headers": {},
    "deadline": 123,
    "timeoutBody": "aSDinaTvuI8gbWludGxpZnk=",
    "timeoutUrl": "<string>",
    "timeoutHeaders": {}
  },
  "messageId": "<string>",
  "deduplicated": true,
  "error": "<string>",
  "workflowRunId": "<string>",
  "workflowCreatedAt": 123
}

Authorizations

bearerAuthbearerAuthQuery

Authorization · string · header · required

QStash authentication token

Path Parameters

workflowRunId · string · required

The workflow run ID to notify.

eventId · string · required

The event ID that waiters are listening for.

Body

application/jsontext/plainapplication/octet-stream

The event data to send to the waiter. This will be the request payload for the waiting workflow step.

The body is of type object.

Response

201

application/json

Event notification sent or saved successfully

waiter · object

The waiter that was notified.

Show child attributes

messageId · string

The ID of the notification message that was published.

deduplicated · boolean

Whether this notification was deduplicated.

error · string

Error message if the notification failed.

workflowRunId · string

The workflow run ID if the notification was sent within a workflow.

workflowCreatedAt · integer<int64>

The timestamp when the workflow run was created (Unix timestamp in milliseconds).