Note: This documentation is for an old version of the Live Event API. For the latest version of this API, click here.
Live event streams allow both you and your users to receive HTTP push notifications for your status page via HTML5 Server-Sent events, or SSEs. Hund notifies subscribers of new issues, updates, status changes, and scheduled issues.
This article will outline how Hund’s SSEs are structured so that you may use them in your own applications.
Endpoints
Hund offers two endpoints to receive live events from: /live and /live/:component_id. To receive all events for an example status page, we could connect to https://example.hund.io/live.
On the other hand, to only receive updates for a particular component, we must supply a component ID, which would look like https://example.hund.io/live/56844edb8fbb65215d000000.
If you're targeting Javascript, the EventSource API will allow you to easily consume and respond to events from our live endpoints. Otherwise, there are a variety of projects that target other languages to suit your needs.
Events
Currently, our live endpoints will send clients four different event types, which are outlined here. Each event type carries a JSON data payload, which is available under each event's data field. Moreover, every event will contain the current state of the status page or component, depending on the endpoint used.
init_event
Example data:
{
"state": "degraded",
"issues": [
{
"id": "57630a2b8fbb654829473756",
"title" :"Heavy Load",
"body": "\u003cp\u003eWe're working on it.\u003c/p\u003e\n",
"label": "investigating",
"component": "Website",
"standing": true,
"scheduled": false,
"created_at": 1466464235,
"updates": []
}
]
}
The init_event is sent immediately upon connecting to a live endpoint, and contains the current state of the status page or component, as well as any relevant issues. This can be used to initialize your own client-side records of the status page, which could be mutated later by new incoming events.
status_event
Example data:
{
"state": "outage",
"status": {
"component": "Memcached",
"state": "degraded"
}
}
The status_event is sent whenever the status of a component changes, and contains a status object.
Please note that the state and status.state fields in the above JSON are two different values, and might not be equal. For example, if you're connected to /live, state represents the global state of your status page, whereas status.state is the current state of the particular component defined by status.component.
However, if you are connected to /live/:component_id, then state would represent the current state of the component, therefore being equal to status.state.
issue_event
Example data:
{
"state": "degraded",
"issue": {
"id": "57630a2b8fbb654829473756",
"title" :"Heavy Load",
"body": "\u003cp\u003eWe're working on it.\u003c/p\u003e\n",
"label": "investigating",
"component": "Website",
"standing": true,
"scheduled": false,
"created_at": 1466464235,
"updates": [
{
"issue_id": "57630a2b8fbb654829473756",
"body": "\u003cp\u003eThings seem stabilized.\u003c/p\u003e\n",
"label":"monitoring",
"created_at": 1466464900
}
]
}
}
The issue_event is sent upon the creation of new issues, and contains all relevant information about the issue. The updates field is ordered newest updates first. If the issue is scheduled, then an issue_event will only be fired if the issue is scheduled within the next week. Scheduled issues also fire issue_events upon beginning and ending.
Scheduled issues contain some extra fields in their issue object, as seen below.
Example data (scheduled issues):
{
"state": "operational",
"issue": {
"id":"57619af28fbb654b21227308",
"title":"Maintenance",
"body":"\u003cp\u003eWe are undergoing some scheduled maintenance.\u003c/p\u003e\n",
"label": "assessed",
"component": "Compression Pipeline",
"standing": true,
"scheduled": true,
"updates": [],
"created_at": 1466030653,
"starts_at": 1466031653,
"ends_at": 1466187233
}
}
Note that starts_at, ends_at, and created_at are all UNIX timestamps.
update_event
Example data:
{
"state": "operational",
"update": {
"issue_id": "57630a2b8fbb654829473756",
"body": "\u003cp\u003eLoad is now back to normal.\u003c/p\u003e\n",
"label": "resolved",
"created_at": 1466464900
}
}
The update_event is sent upon the creation of an issue update, and contains an update object with the relevant issue ID and other information.