POST
/
v2
/
publish
curl -X POST "https://qstash.upstash.io/v2/publish/https://www.example.com" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Upstash-Method: POST" \
  -H "Upstash-Delay: 10s" \
  -H "Upstash-Retries: 3" \
  -H "Upstash-Forward-Custom-Header: custom-value" \
  -d '{"message":"Hello, World!"}'

{
  "messageId": "msd_1234",
  "url": "https://www.example.com"
}

​
Request

​
destination
string
required

Destination can either be a topic name or id that you configured in the Upstash console, or a valid url where the message gets sent to. Make sure the url is prefixed with a valid protocol (http:// or https://)

​
body
string

The raw request message passed to the endpoints as is

​
Content-Type
string

ContentType is the MIME type of the message.

We highly recommend sending a Content-Type header along, as this will help your destination API to understand the content of the message.

For example application/json, application/xml, application/octet-stream, text/plain

​
Upstash-Method
string
default:"POST"

The HTTP method to use when sending a webhook to your API.

​
Upstash-Delay
string

Delay the message delivery.

Format for this header is a number followed by duration abbreviation, like 10s. Available durations are s (seconds), m (minutes), h (hours), d (days).

example: ”50s” | “3m” | “10h” | “1d”

​
Upstash-Retries
int
default:3

How often should this message be retried in case the destination API is not available.

The total number of deliveries is therefore capped at 1 + retries

Leave this empty to use the default value, (free tier: 3, paid tier: 5)

The backoff duration in seconds is calculated as follows: n is the number of times the task has been retried.

min(86400, e ** (2 * n))

​
Upstash-Callback
string

You can define a callback url that will be called after each attempt. See the content of what will be delivered to a callback here

  • The callback url must be prefixed with a valid protocol (http:// or https://)
  • Callbacks are charged as a regular message.
  • Callbacks will use the retry setting from the original request.
​
Upstash-Failure-Callback
string

You can define a failure callback url that will be called when a delivery is failed. That is when all the defined retries are exhausted. See the content of what will be delivered to a failure callback here

  • The failure callback url must be prefixed with a valid protocol (http:// or https://)
  • Callbacks are charged as a regular message.
  • Callbacks will use the retry setting from the original request.
​
Upstash-Forward-*
string

You can send custom headers along with your message.

To send a custom header, prefix the header name with Upstash-Forward-. We will strip efix and them to the destination API.

example: “Upstash-Forward-My-Header: my-value” -> “My-Header: my-value”

​
Response

Either a single object or an array of objects is returned, depending on whether you have sent the message to a url or topic

curl -X POST "https://qstash.upstash.io/v2/publish/https://www.example.com" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Upstash-Method: POST" \
  -H "Upstash-Delay: 10s" \
  -H "Upstash-Retries: 3" \
  -H "Upstash-Forward-Custom-Header: custom-value" \
  -d '{"message":"Hello, World!"}'

{
  "messageId": "msd_1234",
  "url": "https://www.example.com"
}