# Receive events

The entity receiving events can be developed using your preferred programming language.

In order to receive events from the bus, you need to:

Create one (or more) endpoint(s) accepting JSON events via POST.
Register as a node on the bus via the bus admin.

# Register on the bus

The first step to receive events is to register as 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 Receive events and set up your node following the indications on the page.

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

# Structure of events received

The bus routes the events received from the sending nodes to the receiving nodes based on the sending nodes' directions (learn more), after a couple of transformations:

The bus breaks down the arrays of events into single events.
It adds authentication details in the headers, if you requested so.
It appends the specific "node_configuration" provided by the sending node for the receiving node, if any, to the event body.

# Example

Here is an example of an event received by a node, including token based authentication:

The event properties are described in the Send events section of this documentation. Note that the events array has been replaced by one event.

# Event versions

From the end of 2022 (version 2.0.0),

"venture_config_id" will be renamed "from",
"venture_reference" will be renamed "reference",
"service_configuration" will be renamed "node_configuration",
"service_id" will be renamed "node_id",
"culture", "action_type" and "action_reference" will be removed.

The current version (1.1.0) includes both old and new property names to allow existing nodes to transition.

# Event names and payload schemas

We encourage the nodes sending events to leverage pre-defined event names and payload schemas so that receiving nodes can rely on consistent events across different ventures:

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.

When a sending node adds your node as a destination for its events, you will see it on the Event Subscriptions page.

On this page, for each sending node and event name, you can:

Enable or disable the reception of events.
Define the endpoint to which events are sent, if you have registered more than one end point for your node.

You can choose if you want the reception of new events to be enabled or disabled by default on the Details and Settings page.

Even if the reception of events is disabled, the most recent events routed to your node will be visible on the Events and Metrics page, in the section Recent events sent to this node, so that you can test using real events.

# Test

You can send events to your node from the admin and see your node's reponse.

# Send test events

Click on Event Tester in the admin menu.
Edit the event template provided.
Select the action Send event and select your node in the destinations dropdown.
Submit, and find out what is the response from your node.

# Send real events

If you'd like to test using a real example, provided that sending nodes have started to route events to your node,

Go to the Events and Metrics page.
In the section Recent events sent to this node, click on the send icon next to the event of your choice. The event will be adapted and pasted into the Event Tester.
Select the action Send event and select your node in the destinations dropdown.
Submit, and find out what is the response from your node.