Notifications

Info

Available from AC 3.13.4 onwards

Push notifications of alert event messages are available via a secure WebSocket endpoint:
wss://<analyticsDomain>/notifications/ws
NB: there is no /hq prefix.

Notifications correspond to the requested Rollup(s). WebSocket clients must authorize using a JSON Web Token (JWT) as described below.

Connecting

Clients must send the HTTP origin header when initiating the WebSocket connection. This is used to ensure that the same origin is used both to connect to the WebSocket, and to request a JWT from the AC. If origin is missing, the endpoint will respond with 400 Bad Request.

Authorizing

Upon successful connection, the endpoint will issue an authorization challenge. This is in the form of a text frame in JSON format:

{
  "type": "authorization",
  "message": {
    "event": "required",
    "nonce": "cb584e44c43ed6bd0bc2d9c7e242837d"
  }
}

nonce is a unique string generated randomly for each authorization attempt. This string must be included in the JWT request - this ensures that the JWT can be used only once.

URIs corresponding to the Rollup(s) for which the client wishes to see alert messages must also be included in the JWT request.

The JWT endpoint request is described in detail in the authorization section.

Once the JWT is obtained it must be sent in JSON format as a text frame over the WebSocket:

{
  "event": "authorize",
  "token": "eyJraWQiOiJBbU9fNUczRFFlN1VjU3pncUxwNlhfSWxxdk0yRGwzR21nSXdWSU1pSVprIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJjb250ZXh0IjpbeyJ0eXBlIjoicm9sbHVwIiwidXJpIjoiYWMxL29yZzEvdmlldy9yb2xsdXAvMDAxNTgzMTczMDIwMzYwMzkwIn1dLCJ1c2VyQ29udGV4dCI6WyJhZSJdLCJ1c2VybmFtZSI6ImRldkBhZS5jb20iLCJub25jZSI6ImNiNTg0ZTQ0YzQzZWQ2YmQwYmMyZDljN2UyNDI4MzdkIiwiZXhwIjoxNTg5OTgyMzU5LCJpYXQiOjE1ODk5ODIwNTksImF1ZCI6Imh0dHBzOi8vYW5hbHl0aWNzLmFjdHVhbC1leHBlcmllbmNlLmNvbSJ9.s2C_6-L4hjycSTTLNBgl4dZrN5LQWnqztuuSwPMXMIiC-ideM9fg1yA0KmAuU8g_3cGEYA5KeSv9VrGThYFZJY_weBHHDJxzI6bnQ1yK6UPNB3wDW4_N67t-aPPvqrfXmugAamrTX4piDDpyxEAKb0fYVA4isIbCRIGqoJRXamjzC1mVZvtCeXAX5qI3JFHo-2Q0GFRzkN9pmz40eRMP1XQjxkDP9Yrt3SKm3s9r2NRHMZQ7FtEZmPZr_cdfhKkBRBqL6EWx735o3wL0ZRulluWV4tjwt5PEyhwU_UfxJb_MbLESVcRyA8igP8w6UvLVxf0z42L7tcJrdkgbyqSHAw"
}

Upon successful authorization of this token, the WebSocket will reply:

{
  "type": "authorization",
  "message": {
    "event": "success"
  }
}

The WebSocket session is now authorized, and will begin to receive the relevant alert messages as they are produced. The WebSocket session will remain authorized for 5 minutes, and will need to be reauthorized before this expiry time in order to ensure continuity of messages.

Reauthorizing

When the WebSocket authorization session expires (after 5 minutes), the client will receive a new challenge. The client must then respond to the challenge in the same way as the initial authorization request.

The client may request a new challenge at any time (e.g. before expiry, to ensure continuity) by sending the following JSON text frame:

{
  "event": "reauthorize"
}

Events

An authorized WebSocket client will begin to receive events as they are generated. These are text frames in JSON format.

Example open event message:

{
  "type": "broadcast",
  "message": {
    "rollupUri": "ae/ac/view/rollup/001566403324478433",
    "eventUri": "ae/ac/view/scene/001...3246/:eventId",
    "open": "2019-08-16T10:40:00Z",
    "closed": null,
    "alertPercentage": 20,
    "alertingAnalytics": 15,
    "activeAnalytics": 20,
    "inactiveAnalytics": 1,
    "closedReason": null
  }

Example closed event message:

{
  "type": "broadcast",
  "message": {
    "rollupUri": "ae/ac/view/rollup/001566403324478433",
    "eventUri": "ae/ac/view/scene/001...3246/:eventId",
    "open": "2019-08-16T10:40:00Z",
    "closed": "2019-08-19T15:40:00Z",
    "alertPercentage": 20,
    "alertingAnalytics": 15,
    "activeAnalytics": 20,
    "inactiveAnalytics": 1,
    "closedReason": "EV_COND_NOT_MET"
  }
}

Disconnecting

The client may disconnect at any time to end the session. If the session expires, the connection will remain open (though will not receive messages) for a short time before it times out and the server closes the connection.