Events

An analytic event is created each time an alert has been triggered or acknowledged. Each event has an associated task_id that is the returned value from the response of an alert API call.

Analytic events also have an associated name field for correlation that can be programmatically set when an alert is sent via the /alerts endpoint. See Customizing Your Alerts.

Events can be retrieved through a simple GET request to our server into our /events endpoint.

The GET command to send the broadcast should take the following form:

GET /subscribers/{id}/api/v1/events
Authorization: RelayApiKey {apikey}
Content-type: application/json

Headers and Subscriber ID Path

• apikey : you should contact Relay to get your API key, as it is not available via self-service. Your key should be included within the Authorization header. Don’t forget to include “RelayApiKey” before your actual key.

• id : your subscriber ID, which can be found on the Relay Dash through Help → Server Details under Subscriber

Optional Query Parameters

• oldest: An iso8601 timestamp which defaults to 7 days ago

• limit: The maximum number of events returned which defaults to 100

Example

The following example shows a curl command that retrieves the oldest analytic event from August 8th from our server.

$ export subscriber_id=yourcustomersID
$ export apikey=apikey123
$ curl -s -H "authorization: RelayApiKey $apikey" "https://api.relaypro.com/subscribers/$subscriber_id/api/v1/events?oldest=2024-08-08T12:00:30Z&limit=1" | jq
[
 {
  "category": "tasks",
  "content": "{\"task\":{\"id\":\"mCcJawrh3shriXHombQxXA\",\"name\":\"alerts\",\"task_type\":{\"major\":1,\"minor\":4,\"name\":\"alerts\",\"namespace\":\"system\"}},\"type\":\"start\"}",
  "content_type": "application/vnd.relay.tasks.parameters.v2+json",
  "id": "a195f66af5514cacbdbeea09c8e785f6",
  "profile_id": "",
  "source_type": "user",
  "sub_id": "287ced84-9372-4615-a4dd-f41443607a9c",
  "timestamp": "2024-08-08T18:25:40.923947Z",
  "user_id": "",
  "workflow_id": "wf_mCcJawrh3shriXHombQxXA_pEGyLUeP9CRATjQd6HP9A7OD",
  "workflow_instance_id": "0qaNYdHV0LC9CUv9BmrjGIwA"
 }
]

In the JSON object that gets returned, the content field has the detailed information about the event and the following fields determine what kind of analytic event it is:

• task : The JSON object for the specific event

  • id : Unique identifier for the event that should match what was returned when the event was triggered

  • name : Correlation identifier that can be set when event is triggered, defaults to alert

• type: This field represents the kind of event that is being returned and can equal the following:

  • start: event for when the alert was triggered

  • end: event for when the alert is completed (through time out, acknowledgement or error)

  • acknowledged: event for when device acknowledges an alert

  • timed_out: event for when an alert times out and no one has acknowledged it

• device: This field will be present if the event type is acknowledged and represented the user profile associated with the device that acknowledged the alert

• status: This field will be present if the event type is end and the alert has been completed, if the alert was completed without error this should equal normal

The following is an example of the content field for an event for when an alert was triggered:

{
  "task": {
    "id": "mCcJawrh3shriXHombQxXA",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 4,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "type": "start"
}

The following is an example of the content field for an event for when an alert was acknowledged by user 'bob' on a device or virtual account:

{
  "device": "bob",
  "task": {
    "id": "9C9AbxNELsQphK9Afhzr6yG6C",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "type": "acknowledged"
}

The following is an example of the content field for an event for when an alert that timed out:

{
  "task": {
    "id": "mCcJawrh3shriXHombQxXA",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "type": "timed_out"
}

The following is an example of the content field for an event for when an alert was completed:

{
  "status": "normal",
  "task": {
    "id": "9C9AbxNELsQphK9Afhzr6yG6C",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "type": "end"
}