# 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 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.

# Error codes

The bus behaviour is adjusted based on the HTTP response code returned by the receiving node.

# Proper usage of error codes

We recommend that you return:

The appropriate 4xx error code when the service is not able to or will not process a particular event, for example if the payload is malformed or a required field is missing.
The appropriate 5xx error code when the service is temporarily unable to process any event, for instance if it is undergoing maintenance.

# Bus behaviour

In order to give the best chance to events to be delivered successfully, while maintaining the order and without uncecessary retries, the bus behaviour is defined as follows:

Error codes: 400 401 403 404 408 422
Behaviour: The event fails on first attempt.

Error codes: 502 503 504 301 302
Behaviour: The queue is paused while the event at the head of the queue is retried, with exponential backoff, with a maximum interval of 1 minute, for a maximum of 3 hours. The order of events is maintained while the queue is paused.

Other error codes
Behaviour: The event is retried with exponential backoff, for a maximum of 10 seconds. The event then fails, and the next event in the queue is processed.

Note: While error code 500 generally indicates a service-side error, it is sometimes returned due to unforseen difficulties to process a particular event. For this reason, the queue is not paused in such instance. Please watch for events that failed with error 500 on the bus admin!