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.
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 agolimit
: 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 eventtype
: This field represents the kind of event that is being returned and can equal the following:start
: event for when the alert was triggeredend
: event for when the alert is completed (through time out, acknowledgement or error)acknowledged
: event for when device acknowledges an alerttimed_out
: event for when an alert times out and no one has acknowledged it
device
: This field will be present if the eventtype
isacknowledged
and represented the user profile associated with the device that acknowledged the alertstatus
: This field will be present if the eventtype
isend
and the alert has been completed, if the alert was completed without error this should equalnormal
task
: The JSON object for the specific eventid
: 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 stagesname
: Correlation identifier that can be set when event is triggered, defaults toalert
event_id
: An unique identifier for the returned analytic eventtimestamp
: 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"
}
Last updated