Use as Webhook Receiver

You can configure QStash to receive and process your webhook calls.

Instead of having the webhook service call your endpoint directly, QStash acts as an intermediary, receiving the request and forwarding it to your endpoint. QStash provides additional control over webhook requests, allowing you to configure properties such as delay, retries, timeouts, callbacks, and flow control.

There are multiple ways to configure QStash to receive webhook requests.

​

1. Publish

You can configure your webhook URL as a QStash publish request.

For example, if your webhook endpoint is:

https://example.com/api/webhook

Instead of using this URL directly as the webhook address, use:

https://qstash.upstash.io/v2/publish/https://example.com/api/webhook?qstash_token=<QSTASH_TOKEN>

Request configurations such as custom retries, timeouts, and other settings can be specified using HTTP headers in the publish request. Refer to the REST API documentation for a full list of available configuration headers.

If the webhook service does not allow setting custom headers, you can create a URL Group and store default configurations on the QStash server, as explained in the next section.

​

2. URL Group

URL Groups allow you to define server-side templates for publishing messages. You can create a URL Group either through the UI or programmatically.

For example, if your webhook endpoint is:

https://example.com/api/webhook

Instead of using this URL directly, you can use the address for your URL Group and add your webhook endpoint to it:

https://qstash.upstash.io/v2/publish/myUrlGroup?qstash_token=<QSTASH_TOKEN>

You can define default headers for a URL Group, which will automatically apply to all requests sent to that group.

curl -X PATCH https://qstash.upstash.io/v2/topics/myUrlGroup \
    -H "Authorizarion: Bearer <QSTASH_TOKEN>"
    -d '{
        "headers": {
            "Upstash-Header-Forward": ["true"]
        }
    }'

When you save this header for your URL Group, it ensures that all headers are forwarded as needed for your webhook processing.

A URL Group also enables you to define multiple endpoints within group. When a publish request is made to a URL Group, all associated endpoints will be triggered, allowing you to fan-out a single webhook call to multiple destinations.