Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Webhook doc and mention query parameters #420

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update Webhook doc and mention query parameters #420

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions qstash/howto/webhook.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,18 +25,21 @@ 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>
`

<Note>
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](/qstash/api/publish) for a full list of available configuration headers.

<Note>
By default, any headers in the publish request that are prefixed with `Upstash-Forward-` will be forwarded to your endpoint without the prefix.
It’s also possible to pass configuration via query parameters. You can use the lowercase format of headers as the key, such as ?upstash-retries=3&upstash-delay=100s. This makes it easier to configure webhook messages.
</Note>

<Tip>
By default, any headers in the publish request that are prefixed with `Upstash-Forward-` will be forwarded to your endpoint.

However, since most webhook services do not allow header prefixing, we introduced a configuration option to enable forwarding all incoming request headers.

To enable this, set `Upstash-Header-Forward: true` in the publish request or append the query parameter `?upstash-header-forward=true` to the request URL. This ensures that all headers are forwarded to your endpoint without requiring the `Upstash-Forward-` prefix.
</Note>
</Tip>

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

Expand All @@ -46,20 +49,21 @@ 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:
Instead of using this URL directly, you can create a URL Group and add this URL as an endpoint.

`
https://qstash.upstash.io/v2/publish/myUrlGroup?qstash_token=<QSTASH_TOKEN>
https://qstash.upstash.io/v2/publish/<URL_GROUP_NAME>?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 \
curl -X PATCH https://qstash.upstash.io/v2/topics/<URL_GROUP_NAME> \
-H "Authorizarion: Bearer <QSTASH_TOKEN>"
-d '{
"headers": {
"Upstash-Header-Forward": ["true"]
"Upstash-Header-Forward": ["true"],
"Upstash-Retries": "3"
}
}'
```
Expand Down