Knowledge Base

Live Event Streams

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.

Note: this documentation is for version 2 of the Live Event API. For information about version 1, click here.

Endpoints

Hund offers two endpoints to receive live events from: /live/v2/status_page and /live/v2/component/:component_id. To receive all events for an example status page, we could connect to https://example.hund.io/live/v2/status_page.

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/v2/component/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

Our live endpoints will send clients several 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",
      "components": ["Website", "Database"],
      "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 Events

The possible status event types emitted are:
* degraded: a component has gone down
* restored: a component has come back up
* status_created: a newly created component has gone from a pending state to operational

Example data:

{
  "state": "outage",
  "status": {
    "component": "Memcached",
    "state": "degraded"
  }
}

Status events are 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 /status_page, 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 /component/:component_id, then state would represent the current state of the component, therefore being equal to status.state.

Issue Events

The possible issue event types emitted are:
* issue_created: an issue has been created
* issue_started: a scheduled issue has started
* issue_ended: a scheduled issue has ended

Example data:

{
  "state": "degraded",
  "issue": {
    "id": "57630a2b8fbb654829473756",
    "title" :"Heavy Load",
    "body": "\u003cp\u003eWe're working on it.\u003c/p\u003e\n",
    "label": "investigating",
    "components": ["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
      }
    ]
  }
}

Issue events contain all relevant information about the issue. The updates field is ordered newest updates first. If a newly created issue is scheduled, then issue_created will only be fired if the issue is scheduled within the next week.

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",
    "components": ["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.

Issue Update Events

The possible issue update event types emitted are:
* issue_updated: an issue update has been created
* issue_resolved: a resolving issue update has been created, thus resolving the issue

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
  }
}

Update events contain an update object with the relevant issue ID and other information.