Events
Events are notifications generated by Janus that give information about any updates or changes occurring at various stages of its lifecycle. An event is generated every time there is a change in the state of Janus execution, such as the completion of a data gatherer by a rater, or the creation of a new session. Events can be observed by interested and authorized parties and actions outside of the Janus system may take place based on events raised by assessment participants’ actions or processing activity.
Janus offers a fixed set of notifications but does allow per-action control to subscribers so they can choose which of these events they receive.
Types of events
| Event Name | Applicable Endpoints | Description |
|---|---|---|
| Invoked | Evaluator, Enrichment, EnrichmentTransformer | Processing on this run has started. Will always fire input validation was successful. |
| Created | Session, DataGatherer | The instance has been created, but there may be more steps to complete. Only fires upon successful instance creation. |
| ResultsAvailable | DataGatherer, Evaluator, Enrichment, EnrichmentTransformer | The results of the endpoint are available to fetch. Will only fire if the run was successful. |
| Complete | Session, DataGatherer, Evaluator, Enrichment, EnrichmentTransformer | Processing has completed, regardless of whether or not the run was successful. Contains errors and other informational status codes for the run. |
All events contain the same information, except for a “details” array that is only present in the Complete events. This details array has the same structure as the details array received in a Janus response but contains details for the entire run. This includes information about processing that occurs after an asynchronous response. In other event types, the details property will be null.
Registering and Using Events:
To receive these events and utilize them, the following steps need to be followed:
- Set up and provide a webhook, configured to receive CloudEvents v1.0 schema events. This webhook URL must be delivered to MHS for registration of the webhook to Janus events.
- Through the Session or individual lifecyle endpoints, specify which events should be subscribed to. Only subscribed events will be delivered to the webhook.
- Use the received events to trigger actions in the system workflow. For example, upon receiving an “Enrichment Complete” event, send the GET Enrichment request to Janus to retrieve the completed enrichment
Webhook Setup
Janus events adhere to the CloudEvents v1.0 schema, a specification used to describe how events are structured and sent. To receive these events, a publicly accessible HTTPS webhook must be set up, and the event data will be sent as a request to this webhook.
The webhook must handle two types of requests:
A POST request, which will contain the event being sent. The webhook should be set up to receive POST requests. The endpoint must use the OAuth 2.0 Bearer Token model (RFC6750) for authorization. The body of the request sent by the Janus API will match a consistent and specific schema, with properties enforced by the CloudEvents schema standard as well as several specific to the Janus API.
An OPTIONS request, which is used for the validation handshake between the event sender and webhook. A validation handshake is required in order to successfully register the webhook to Janus events. This handshake will be sent at the time that the webhook is registered by MHS. The response must be configured to include several headers including “Webhook-Allowed- Origin” and “Webhook-Described-Rate”, as specified in CloudEvents documentation.
Note that webhook registration is tied to a specific tenant, so development and production environments may optionally have separate webhooks.
CloudEvents v1.0 schema is defined with the following properties:
| Property Name | Description |
|---|---|
| data | An object that can be used to contain custom properties for an event. The Janus API makes use of two custom properties, "details" and "jobRunStartTime". |
| id | The unique identifier for this event. Randomly generated upon event creation. |
| source | A URI that identifies the specific context for which an event occurred. In the Janus API, this is the endpoint that was called to produce the event. |
| specversion | The version of the CloudEvents specification used by the event. |
| subject | Describes the source of the event, typically to assist with filtering and routing scenarios. In the Janus API, this contains multiple IDs that describe where the event was originated and where it should be routed, in the format {subscriberID}/{sessionID}/{templateID}/{resourceID} |
| time | Timestamp of when the action that the event is describing took place. |
| type | Contains a value that describes the type of event, related to where the event was fired from. In Janus, this value describes both the endpoint that the event was created in and the specific event type. |
The Janus API makes use of two custom properties within the "data" object in the event:
| Property Name | Description |
|---|---|
| details | Provides info about the run in the same format as the “details” array within Janus responses. |
| jobRunStartTime | The time that the processing began on the run. |
The full webhook documentation for CloudEvents v1.0 schema can be found on Github: CloudEvents Schema documentation.
Subscribing to Events
Once a webhook is configured, it is important to specify which events should be subscribed to. Only subscribed events will be passed on to the webhook. If no Event Notification information is specified in the Janus requests, no events will be sent, even if the webhook is registered successfully.
There are two ways of doing this:
1. Set up Event Notification flags during session set-up (recommended)
When sending a request to create a new session, there is an optional body property to specify which events should be sent back and which should not. To subscribe to an event, use the “eventNotifications” property of the session request (as shown in the figure below). The events that are marked true will be sent back while the ones marked false will not.
2. Set Event Notification flags on each call to Janus
After the session has been set up, there is still a way to subscribe or unsubscribe to certain events. Events related to the Data Gatherers can be managed within the Data Gatherer requests, and the same can be done for Evaluators and Enrichments. The same “eventNotifications” field is available in each of these requests, containing only the events related to that specific lifecycle stage. For example, the eventNotifications for an Enrichment could look like the following:
Using Events and Webhooks
Events will provide updates as soon as they occur, which will allow enrichment retrieval to occur as soon as the enrichment is ready. Continuous polling for status is inefficient and can be resource-intensive when checking the status of many assessments. Events eliminate the need for these extra requests. Through the elimination of these extra requests, the system can become more scalable and cost-effective to operate.
Additionally, the Complete events can be used to receive additional details about asynchronous runs that would not be seen in the response.
Routing events to different servers (using Routing Codes)
Routing codes are optional three-character values set during session creation you can use to redirect events. They’re encoded in the last six characters of the sessionID and can be decoded to identify the routing code. This enables clients to route events by region, environment, or workflow—without needing multiple web-hooks. It’s a scalable, flexible way to manage routing across systems.
→ See Routing Codes for more information.