Knowledge Base

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, percent uptime, and incident-free streak (in seconds) of the status page or component, depending on the endpoint used.

init_event

Example data (/live/v2/status_page):

{
  "state": "degraded",
  "incident_free_streak": 6560509.85,
  "percent_uptime": 100.0,
  "issues": [
    {
      "id": "57630a2b8fbb654829473756",
      "title" :"Heavy Load",
      "body": "\u003cp\u003eWe're working on it.\u003c/p\u003e\n",
      "label": "Investigating",
      "components": [
        {
          "id": "57a3761c8fbb652a349ebb95",
          "name": "a1",
          "description": "\u003cp\u003ethis is the stuff\u003c/p\u003e\n",
          "state": "degraded"
        },
        {
          "id": "57a376398fbb652a349ebb99",
          "name": "a2",
          "description": null,
          "state": "outage"
        }
      ],
      "standing": true,
      "scheduled": false,
      "created_at": 1466464235,
      "updates": []
    }
  ],
  "groups": [
    {
      "id": "57a371798fbb6517d9c13d6b",
      "name": "Regions",
      "description": "\u003cp\u003e\u003cstrong\u003eMy Description\u003c/strong\u003e\u003c/p\u003e\n",
      "state": "outage",
      "components": [
        {
          "id": "57a3761c8fbb652a349ebb95",
          "name": "a1",
          "description": "\u003cp\u003ethis is the stuff\u003c/p\u003e\n",
          "state": "degraded"
        },
        {
          "id": "57a376398fbb652a349ebb99",
          "name": "a2",
          "description": null,
          "state": "outage"
        }
      ]
    },
    {
      "id": "56bbc6c18fbb650f76a984ed",
      "name": "Services",
      "description": "",
      "state": "operational",
      "components": [
        {
          "id": "59e029a98fbb654cc7973877",
          "name": "Compression Pipeline",
          "description": null,
          "state": "operational"
        }
      ]
    }
  ]
}

Example data (/live/v2/component/:component_id):

{
  "state": "operational",
  "incident_free_streak": 7002.56,
  "percent_uptime": 100.0,
  "issues": [],
  "component": "Website",
  "id": "5c0597968fbb65645a7857f7",
  "name": "Website",
  "description": "",
  "group": {
    "id": "57a371798fbb6517d9c13d6b",
    "name": "Services",
    "description": "",
    "state": "outage"
  }
}

The init_event is sent immediately upon connecting to a live endpoint, and contains the current state of the status page (plus all groups and their components) 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",
  "incident_free_streak": 65605.12,
  "percent_uptime": 100.0,
  "status": {
    "component": {
      "id": "5c0597968fbb65645a7857d4",
      "name": "Memcached",
      "description": "",
      "group": {
        "id": "57a371798fbb6517d9c13d6b",
        "name": "Infrastructure",
        "description": "",
        "state": "outage"
      },
      "state": "outage"
    },
    "state": "outage"
  }
}

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.

status.state is also equivalent to status.component.state for these events. However, status.component.group.state may be different from these previous fields, since the state of the group is dictated by other components in the group as well.

Issue Events

The possible issue event types emitted are:

• issue_created: an issue has been created
• issue_retrospectively_created: a retrospective issue has been created
• informational_issue_created: an informational bulletin/announcement issue has been posted
• issue_started: a scheduled issue has started
• issue_ended: a scheduled issue has ended
• issue_cancelled: a scheduled issue has been cancelled (note the double "l" in the event name)

Example data:

{
  "state": "degraded",
  "incident_free_streak": 65605.12,
  "percent_uptime": 99.9987,
  "issue": {
    "id": "57630a2b8fbb654829473756",
    "title" :"Heavy Load",
    "body": "\u003cp\u003eWe're working on it.\u003c/p\u003e\n",
    "label": "Investigating",
    "components": [
      {
        "id": "5c0597968fbb65645a7857f7",
        "name": "Website",
        "description": null,
        "state": "degraded",
        "group": {
          "id": "57a371798fbb6517d9c13d6b",
          "name": "Services",
          "description": "",
          "state": "outage"
        }
      }
    ],
    "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",
  "incident_free_streak": 65605.12,
  "percent_uptime": 99.9987,
  "issue": {
    "id":"5b619af28fbb654b21227308",
    "title":"Maintenance",
    "body":"\u003cp\u003eWe are undergoing some scheduled maintenance.\u003c/p\u003e\n",
    "label": "Maintenance",
    "components": [
      {
        "id": "59e029a98fbb654cc7973877",
        "name": "Compression Pipeline",
        "description": null,
        "state": "operational",
        "group": {
          "id": "56bbc6c18fbb650f76a984ed",
          "name": "Services",
          "description": "",
          "state": "operational"
        }
      }
    ],
    "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
• issue_addended: an issue addendum/postmortem update has been created
• issue_reopened: a resolved issue was reopened

Example data:

{
  "state": "operational",
  "incident_free_streak": 65605.12,
  "percent_uptime": 99.9987,
  "update": {
    "issue_id": "57630a2b8fbb654829473756",
    "body": "\u003cp\u003eLoad is now back to normal.\u003c/p\u003e\n",
    "label": "Resolved",
    "created_at": 1466464900,
    "issue_components": [
      {
        "id": "5c0597968fbb65645a7857f7",
        "name": "Website",
        "description": null,
        "state": "operational",
        "group": {
          "id": "57a371798fbb6517d9c13d6b",
          "name": "Services",
          "description": "",
          "state": "operational"
        }
      }
    ]
  }
}

Update events contain an update object with the relevant issue ID and other information. In the case of issue_reopened, an additional issue field containing the full issue object is made available within the update object.

Cache Events

Certain data, such as the incident-free streak and percent uptime, rely on caches to quickly compute current values. To ensure these values are up-to-date in a live connection, we send cache events with the new values of all basic data for the endpoint. The possible cache event types emitted are:

• cache_grown: a cache was grown (new data added)
• cache_rebuilt: a cache was rebuilt from scratch

Example data:

{
  "state": "operational",
  "incident_free_streak": 1172.194,
  "percent_uptime": 100.0
}