Ringier Event Bus

# Send events

# Register on the bus

The first step is to create a node on the bus. Nodes are entities that emit events, receive events or both.

  • Log in to the bus admin. You will find the link in the top-right corner of this page.
  • On the Nodes page, click on the button Add New.
  • After providing a name, description and contact details, enable the option to Emit events.
  • Choose a username and password. Together with the node id, they are the credentials required to authenticate if you are going to send events via the API.

We suggest that you register the node on both the staging and production environments.

# Choose a method to send events to the bus

There are three methods for sending events to the Ringier event bus.

# 1. Using a client library

For platforms built with Laravel (versions 10 and higher) or WordPress, we offer client libraries that enable seamless integration:

Reach out to the bus team if you need support or to add your contribution to the list above.

# 2. Sending events to an Amazon SQS queue

You can send events to an Amazon SQS queue on the bus. This method offloads the responsibility of queuing events to the bus infrastructure, simplifying your setup. It is our recommended method for sending events. Read more about this method.

# 3. Sending events to the Bus API

Alternatively, you can send events to the bus by making POST requests to its API endpoint. Detailed information on this method can be found here.

The bus API adheres to OWASP ASVS standards and the OWASP Top 10, and complies with the API security standards and best practices (opens new window) as well as the guidelines provided by APIsec.ai (opens new window).

# Event and payload specifications

To use existing services, and for services to be able to rely on consistent events across different ventures, you can leverage pre-defined event names and payload schemas:

Feel free to add more events and payload schemas to these documents and to contact Delphine from the Bus team if you have any questions.

# Event routing

You can define to which nodes your events are routed by adding destinations in the admin.

  • Log in to the bus admin. You will find the link in the top-right corner of this page.
  • On the Nodes page, select your sending node in the list.
  • Access the menu Event Destinations.
  • Add destination(s) for your event(s).

# Filtering events by name

You can select events to route to a destination by filtering on the event name.

Wild cards: The event name accepts ? as a wild card to represent one character and * as a wild card to represent one or more characters.
Example: "Listing*" can be used to route "ListingCreated", "ListingUpdated" and "ListingDeleted" in one trigger.

# Filtering events by route

Optionally, you can select events to route to a destination by filtering on the route.

Example of use case: You are working with a new third party and you need to import all articles currently online on your site into their content library. You can write a script to trigger "ArticleCreated" events for all online articles with a specific route value, and use this route value to ensure that those events only reach the service in charge of syncing content with this new third party.

To filter events by route, you first need to access the Details and Settings page and choose to define event destinations based on Event name and route. On the Event Destinations page, you will then be able to specify the route.

Note: An empty route will only match events where the route is an empty string or not specified. * will match any route, except special bus routes prefixed with "bus-".

# Authentication to the receiving node

If authentication is required by the receiving node, you will find an Authentication in the destination details. Contact the receiving node to get credentials. Then, enter the name and value in the corresponding fields. The bus will insert them in the headers when calling the node's endpoint.

# Configuration data

The bus allows to store configuration data such as settings and credentials to communicate with third parties in your name, so that you don't have to include them in the payload of every event.

If the receiving node requires such data, you will find a Configuration data section in the destination details.

Depending on the receiving node settings, the data will either

  • be appended to each event received by the bus and routed to the receiving node,
  • or sent to the receiving node when updated, and stored by the receiving node.

You may contact the receiving node to confirm the expected data and format.

# Destination inheritance

All nodes inherit destinations (including configuration data) defined at the bus level and at the parent node level, if any. To define a parent node and access the details of inherited settings, click on Inherited destinations in the top right corner of the Event Destinations page.

Some destinations are defined at the bus level so that all nodes benefit from default functionalities such as event counting and monitoring, storing of the last 100 events sent for debugging (displayed on the Events and Metrics page) or the automatic sending of notifications to Slack.

You may define a parent node if you need to set up the same destinations (including configuration data) for several nodes.

If you wish to disable an inherited destination, you can create the same destination at the node level and disable it.

# Receive a response

Some receiving nodes may communicate information back to you. You then need to implement a REST endpoint accepting events sent via a POST call. Learn how to receive events.

# Testing

You can test your events' structure and confirm to which nodes they will be routed.

# Validate event structure

Event validation enables you to:

  • Check if the event complies with the structure described here.
  • If the event is one of the events specified in the specifications and the payload schema has been added to the event validator source code (opens new window), it will check that the payload structure complies with the specification. You are welcome to contribute to the payload schemas' definition.

# From the admin

Click on Event Tester in the admin menu, paste an event and select the action Validate event structure. The validation feedback will appear below.

# From your application

Send an event to the bus from your application using the route "bus-validation" like in the example below. Your event will not be routed to any nodes. The bus response will indicate whether the event is valid, whether the payload complies with the specifications (if the payload schema is defined) and what the errors are.

# Test event routing

The admin can confirm to which nodes an event will be routed.

  • Click on Event Tester in the admin menu
  • Paste an event, or simply enter an event name and eventually a route value
  • Select the action Dry run (verify destinations)
  • Submit and find out to which nodes the event would be routed.

# View events sent

You can see the last 100 events sent received by the bus.

  • Click on Events and Metrics in the admin menu and look at Recent events emitted.