Topics

Sending messages to a single endpoint and not having to worry about retries is already quite useful, but we also added the concept of topics to QStash.

In short, a topic is just a namespace where you can publish messages to, the same way as publishing a message to an endpoint directly.

After creating a topic, you can create one or multiple endpoints. An endpoint is defined by a publicly available URL where the request will be sent to each endpoint after it is published to the topic.

When you publish a message to a topic, it will be fanned out and sent to all the subscribed endpoints.

When should I use topics?

Topics decouple your message producers from consumers by grouping one or more endpoints into a single namespace.

Here’s an example: You have a serverless function which is invoked with each purchase in your e-commerce site. You want to send email to the customer after the purchase. Inside the function, you submit the URL api/sendEmail to the QStash. Later, if you want to send a Slack notification, you need to update the serverless function adding another call to QStash to submit api/sendNotification. In this example, you need to update and redeploy the Serverless function at each time you change (or add) the endpoints.

If you create a topic product-purchase and produce messages to that topic in the function, then you can add or remove endpoints by only updating the topic. Topics give you freedom to modify endpoints without touching the backend implementation.

Check here to learn how to publish to topics.

How topics work

When you publish a message to a topic, we will enqueue a unique task for each subscribed endpoint and guarantee successful delivery to each one of them.

Consider this scenario: You have a topic and 3 endpoints that are subscribed to it. Now when you publish a message to the topic, internally we will create a task for each subscribed endpoint and handle all retry mechanism isolated from each other.

How to create a topic

Please refer to the howto here.