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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://qstash-eu-central-1.upstash.io/v2/notify/{workflowRunId}/{eventId}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://qstash-eu-central-1.upstash.io/v2/notify/{workflowRunId}/{eventId}"
	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://qstash-eu-central-1.upstash.io/v2/notify/{workflowRunId}/{eventId}"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://qstash-eu-central-1.upstash.io/v2/notify/{workflowRunId}/{eventId}')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{}'

response = http.request(request)
puts response.read_body

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