Publish Messages

Publishing a message is as easy as sending a HTTP request to the /publish endpoint. All you need is a valid url of your destination.

info

Destination URLs must always include the protocol (http:// or https://)

The message

The message you want to send is passed in the request body. Upstash does not use, parse, or validate the body, so you can send any kind of data you want. We suggest you add a Content-Type header to your request to make sure your destination API knows what kind of data you are sending.

Sending custom HTTP headers

In addition to sending the message itself, you can also forward HTTP headers. Simply add them prefixed with Upstash-Forward- and we will include them in the message.

Here's an example

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H 'Upstash-Forward-My-Header: my-value' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v1/publish/https://example.com'

In this case, we would deliver a POST request to https://example.com with the following body and headers:

// body
{ "hello": "world" }

// headers
My-Header:      my-value
Content-Type:   application/json

What happens after publishing?

When you publish a message, it will be durably stored in an Upstash Redis database. Then we try to deliver the message to your chosen destination API. If your API is down or does not respond with a success status code (200-299), the message will be retried and delivered when it comes back online. You do not need to worry about retrying messages or ensuring that they are delivered.

Publish to topic

Topics allow you to publish a single message to more than one API endpoints. To learn more about topics , check topics section.

Publishing to a topic is very similar to publishing to a single destination. All you need to do is replace the URL in the /publish endpoint with the topic name.

https://qstash.upstash.io/v1/publish/https://example.com
https://qstash.upstash.io/v1/publish/my-topic

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v1/publish/my-topic'

Optional parameters and configuration

QStash supports a number of optional parameters and configuration that you can use to customize the delivery of your message. All configuration is done using HTTP headers.

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 in:header
Upstash-Callback	string You can define a callback url that will be called with the response from the destination API. Callbacks are experimental, and the API might change in the future! 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-Content-Based-Deduplication	boolean If true, the message content will get hashed and used as deduplication id. If a duplicate message is detected, the request will be accepted but not enqueued. The content based hash includes the following values: All headers prefixed with Upstash this includes all custom headers you are sending. The entire raw request body The destination from the url path We store deduplication ids for 90 days. Afterwards it is possible that the message with the same deduplication id is delivered again. When scheduling a message, the deduplication happens before the schedule is created. Messages created by schedules are not deduplicated.
Upstash-Cron	string Cron allows you to send this message periodically on a schedule. Add a Cron expression and we will requeue this message automatically whenever the Cron expression triggers. We offer an easy to use UI for creating Cron expressions in our console or you can check out Crontab.guru. Note: it can take up to 60 seconds until the schedule is registered on an available qstash node.
Upstash-Deduplication-Id	string Provide a unique id for deduplication. This id will be used to detect duplicate messages. If a duplicate message is detected, the request will be accepted but not enqueued. Deduplication ids must not contain : or whitespace. We store deduplication ids for 90 days. Afterwards it is possible that the message with the same deduplication id is delivered again. When scheduling a message, the deduplication happens before the schedule is created.
Upstash-Delay	string Delay the first delivery attempt. Format for this header is a number followed by duration abbreviation, like 10s. Available durations are s (seconds), m (minutes), h (hours), d (days). Overridden by Upstash-Not-Before if both are provided.
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 the prefix and them to the destination API.
Upstash-Not-Before	integer <int64> Delay the first delivery attempt until this time Unix timestamp with second precision. This overrides Upstash-Delay if both are provided.
Upstash-Retries	integer <int64> How often should this messasge 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))

{

• "Content-Type": "string",
• "Upstash-Callback": "https://example.com/callback",
• "Upstash-Content-Based-Deduplication": true,
• "Upstash-Cron": "*/5 * * * *",
• "Upstash-Deduplication-Id": "\"abcdef\"",
• "Upstash-Delay": "\"50s\" | \"3m\" | \"10h\" | \"1d\"",
• "Upstash-Forward-*": "\"Upstash-Forward-My-Header: my-value\" -> \"My-Header: my-value\"",
• "Upstash-Not-Before": 1657093973,
• "Upstash-Retries": 3

}