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

1 min read

post/v2/notify/{workflowRunId}/{eventId}

Request example

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

import requests

url = "https://qstash-eu-central-1.upstash.io/v2/notify/{workflowRunId}/{eventId}"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://qstash-eu-central-1.upstash.io/v2/notify/{workflowRunId}/{eventId}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
});

const data = await response.json();
console.log(data);

Response

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

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

post/v2/notify/{workflowRunId}/{eventId}

Authorization

Authorizationstringheaderrequired#

QStash authentication token

1 alternative authorization method available — see the spec for details.

Path parameters

workflowRunIdstringrequired#

The workflow run ID to notify.

eventIdstringrequired#

The event ID that waiters are listening for.

Body

application/json · text/plain · application/octet-stream

bodyobject#

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

Responses

application/json

Event notification sent or saved successfully

waiterobject#

Show child attributes

urlstring#

The URL that is waiting for the event notification.

headersobject#

The HTTP headers to send with the notification.

Show child attributes

{key}string[]#

deadlineinteger#

The Unix timestamp in seconds when the wait operation times out.

timeoutBodystring#

The body to send if the wait times out.

timeoutUrlstring#

The URL to call if the wait times out.

timeoutHeadersobject#

The HTTP headers to send with the timeout callback.

Show child attributes

{key}string[]#

messageIdstring#

The ID of the notification message that was published.

deduplicatedboolean#

Whether this notification was deduplicated.

errorstring#

Error message if the notification failed.

workflowRunIdstring#

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

workflowCreatedAtinteger#

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

Notify Event List Waiters