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, the API will return no more than 100 events

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": {"type":"start"},
  "task": {"id": "mCcJawrh3shriXHombQxXA","name": "alerts","task_type": { "major": 1,
  "minor": 4, "name": "alerts", "namespace": "system"}},
  "event_id": "a195f66af5514cacbdbeea09c8e785f6",
  "timestamp": "2024-08-08T18:25:40.923947Z"
 }
]

In the JSON object that gets returned details information about the event and the following fields determine what kind of analytic event it is:

• content: This field contains information on the event type as well as any external metadata that may have been sent with the event

  • 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

• task : The JSON object for the specific event

  • id : Identifier for the task that will be same for every event relevant to the triggered alert (start, acknowledge, time_out, end), this allows you to track a task throughout each different stages

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

• event_id: An unique identifier for the returned analytic event

• timestamp: The time at which the event occured

The following is an example returned for an event for when an alert was triggered:

{
  "category": "tasks",
  "content": {  
              "type":"start"
              },
  "task": {
    "id": "mCcJawrh3shriXHombQxXA",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 4,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "event_id": "XXX",
  "timestamp": "2024-08-08T18:25:40.923947Z"
}

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

{
  "category": "tasks",
  "content": {
              "type":"acknowledged",
              "device": "bob" 
            },
  "task": {
    "id": "9C9AbxNELsQphK9Afhzr6yG6C",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "event_id": "XXX",
  "timestamp": "2024-08-08T18:25:40.923947Z"
}

The following is an example returned for an event for when an alert that timed out:

{
  "category": "tasks",
  "content": {  
              "type":"timed_out"
              },
  "task": {
    "id": "mCcJawrh3shriXHombQxXA",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "event_id": "XXX",
  "timestamp": "2024-08-08T18:25:40.923947Z"
}

The following is an example returned for an event for when an alert was completed:

{
  "category": "tasks",
  "content": {  
              "type":"end",
              "status": "normal"
              },
  "task": {
    "id": "9C9AbxNELsQphK9Afhzr6yG6C",
    "name": "alerts",
    "task_type": {
      "major": 1,
      "minor": 2,
      "name": "alerts",
      "namespace": "system"
    }
  },
  "event_id": "XXX",
  "timestamp": "2024-08-08T18:25:40.923947Z"
}