Fundamentals¶

There are a couple concepts we need to address in order to understand how subscriptions work.

Topic¶

Topics are the central component of the subscriptions engine. A topic defines a named channel or subject that messages, events, or pieces of information are grouped under so that publishers and subscribers know what they’re dealing with.

Topics are expected to be defined in a business-oriented way and must follow an established structure that should look somehow like this:

bounded-context/entity/event

!!!note This structure is merely guiding and can be modified if required, although we always expect that topics are defined following business concepts and share a similar structure for related subjects.

The key concept to be stated here is that topics ultimately define subjects. Backend services can define these topics and users subscribe on these topics in order to receive notifications about such subjects.

Channel¶

A channel represents the delivery method that is used when sending data to the subscribers of a topic, such as email, in-app notifications or even SMS. When subscribing to a topic, users can choose which channels to be used for delivery as long as such channel is supported by the specified topic.

Template¶

Templates are used to translate data that is structured in a very low-level format (for example, the JSON payload associated with a messaging event) into something that is fit for presentation to subscribers when a notification is to be sent. In short, templates are used to go from this

JSON
{
    "name": "claim-submitted",
    "payload": {
        "code": "C01",
        "submittedBy": "John Doe",
        "submittedAt": "2025-08-05T18:12:54.2080268Z"
    }
}

To this.

Text Only
1 2	`The claim with code C01 was submitted by John Doe on August 5th, 2025 at 6:12pm.`

Templates are defined per channel since we might need a different format for an email and an in-app notification.

Continue reading¶

Integration