Events Hub Quick Guide

This quick guide was created to help you understand how Sensedia Events Hub works. It gives you an overview of how to:

  • configure routes for sending and receiving events;

  • apply security policies and automatic retries to distribute events to subscribers.

The links included here lead to more detailed sections of our documentation.

Glossary

Throughout the documentation, you will see some terms specific to the messaging context. To make understanding easier, we explain them:

  • Publishers: are the remote applications responsible for creating events and sending them to the Events Hub.

  • Subscribers: are the receivers, applications or customer partners who receive the events and can take actions based on them.

  • Business moments: are business opportunity moments that, using the Events Hub, can be leveraged to generate revenue.

General operation

Events Hub allows you to manage an event distribution architecture from a low-code interface, which doesn’t require advanced programming knowledge. Within it, you can register and manage event publishers and subscribers completely independently.

get starded en

For Events Hub to know which subscribers should receive which events, there are publication and subscription routes, forming a channel for event reception and distribution. These routes are defined through topics, handlers and contexts, each with a specific path that is added to the publication URL. When publishers submit requests to Events Hub, we guarantee that they are distributed only to registered subscribers for that event.

In addition to managing event publication and subscription, Events Hub ensures delivery to subscribers through:

  • tracking the sending status;

  • automatic delivery attempts;

  • manual resend through the interface in case of failure.

To ensure security throughout the events management process, you can add interceptors in the receiving flow. This allows you to control the access of publishers, which can be validated by an external server.

For subscribers, we include a digital signature along with all distributed events to validate the origin of requests. In addition, you can configure a static or dynamic security token for secure information traffic.

Topics, handlers and contexts

Topics, handlers and contexts are the elements that form the event publishing and subscription channel. They organize the routes for receiving and distributing events, ensuring that messages reach the correct subscribers.

Topics

The topic is the last placeholder of the publication URL and it’s through it that the Events Hub finds the subscribers that should receive each event. Publishers send requests using the publication URL of the topic, and Events Hub forwards the events to all of the topic’s active subscribers.

Handlers

Handlers are topic aggregators, used to group topics logically. They are also responsible for applying security policies and event delivery, which will be shared with all topics within it.

Contexts

Contexts allows you to reuse topics in different scenarios. The external authorization server is defined by context, which means that when two different contexts are made available for a topic, it’s possible to use two different authorization endpoints for the same topic.

The event publication URL is divided into parts: the base (unique per client) and placeholders, which are context, handler and topic: <base-url>/<context>/<handler>/<topic>.

Example: Same topic in different scenarios

If you have a handler called "Alerts", in the path /alerts, alert topics are grouped from APIs monitoring. One of these topics is /latency, to distribute latency alert events.

In this scenario, you can choose to:

  • Not register any context. When this happens, Events Hub sets the context to "Default", and no mark is added to the publishing URL. Therefore, requests for the latency topic will be sent to <base-url>/alerts/latency, and all active subscribers in it will receive the events.

  • Register a context to, for example, define environments. In a test scenario, where you don’t want the subscribers of the topic to receive alerts, you can register the testing context and enable it for the latency topic.

To register subscribers in the context, you must link them to the latency topic and enable them only for the testing context. Thus, events sent to <base-url>/testing/alerts/latency will be distributed only to subscribers of that context.

The testing context also allows the use of an authorization mock so that your team doesn’t need to validate credentials of the default context’s authorization endpoint.

Configuring topics, handlers and contexts

For registering handlers with context, we recommend pre-registering the context on the Contexts screen.

Handlers are created and managed on the Handlers screen. In the handler’s registration and editing screen, you can:

  • create and edit topics and policies;

  • assign contexts to topics by clicking the expand icon on the registration screen. They must be previously registered via Contexts screen.
    Publisher authorization endpoints are defined for each context on the Authorizations screen.

handler creation
Contexts, handlers, and topics registration

Publishers and subscribers

Events Hub allows the two sides of event integration, producers and consumers, to be registered in an intuitive and independent way.

Publishers are the source of events. They are registered on the Publishers screen. You can create them or import an app from the Sensedia API Platform.

During registration, you connect the publisher to the topics to which it will send events. Additionally, you choose which contexts will be shared with it.

Publisher registration and management screen

publisher screen

Subscribers are who receive the events. They are registered on the Subscribers screen. When registering a subscriber, you subscribe them to the topics they will receive events from and also choose which contexts will be shared with them.

For subscribers, you need to set up a URL for each topic that will receive events. With this, the same subscriber can receive events at different URLs.

subscribers create topics subscribed
Subscriber registration: definition of the subscriber URL

Security policies for publishers

On the Policies screen, you can define the security measures for publishers and event delivery to subscribers. This includes:

  • the number of automatic delivery retry attempts that will be made;

  • request timeout;

  • returned HTTP status codes that trigger automatic new attempts.

Security for publishers is ensured by interceptors that validate their identity, such as OAuth, JWT, Client ID and Access Token. In addition, you can filter publishers' access by IP.

policies flow
Policy settings: security section
policies retry settings
Policy settings: delivery configuration section

The policies registered on the Policies screen are applied to handlers in the process of creating/editing handlers. This means that all topics grouped under a handler use the same policy. The external publisher authorization server is defined at the context level on the Authorizations screen.

Security when connecting to subscribers

Events Hub implements layers of security that allow subscribers to verify the origin of messages received.

First, we pass a digital signature in all requests to subscribers. This signature is a JWT token generated from a mutual-knowledge key (known by the subscriber and Events Hub), sent when registering subscribers.

As another security requirement for subscribers, it’s possible to configure a static or dynamic token that must also be passed in requests.

subscribers create security
Subscriber registration: step to send mutual-knowledge key and configure a security token

Event details and manual delivery retries

The Event Status screen displays the list of events received from publishers.

event status
List of events received from publishers

You can follow the events received in detail via the Event Status screen. For each event, the attempts and distribution history to subscribers are shown.

event status delivery details
List of events: delivery details
Automatic delivery attempts follow the exponential backoff algorithm to increase the chances of success. However, if all submissions to a subscriber fail, manual deliveries may be attempted on the Delivery Retry screen.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]