Events
Use the Event API to integrate your monitoring or ticketing tools with ilert. It provides a single API endpoint that allows you to create, accept and resolve alerts in ilert. It is designed around the notion that monitoring tools send events when
a problem occurs (an
ALERT
event in ilert terminology)a problem is acknowledged, indicating that someone is working on the resolution of the problem (an
ACCEPT
event)a problem is resolved (a
RESOLVED
event)
The API accepts these events, routes them to the alert source to which the integration key belongs, and takes appropriate action.
An event object contains the following attributes:
integrationKey
Required. The integration key of the alert source.
eventType
Required. Must be either ALERT
, ACCEPT
, or RESOLVE
summary
Required. The event summary. Will be used as the alert summary if a new alert is created.
details
Optional. The event details. Will be used as the alert details if a new alert is created.
alertKey
Optional. For ALERT
events, the alertKey can be used to deduplicate or group events. If an open alert with the key already exists, the event will be appended to the alert's event log. Otherwise a new alert will be created. For ACCEPT
and RESOLVE
events, the alertKey is used to reference the open alert which is to be accepted or resolved by this event.
priority
Optional. Must be either HIGH or LOW. Will overwrite the evaluated priority of the alert source.
images
Optional. A list of images containing src, href and alt.
links
Optional. A list of links, containing href and text.
customDetails
Optional. Additional custom details for the event.
routingKey
Optional. Overwrite escalation policy for ALERT events.
Getting started
Before you can start making API requests, you need to create an API alert source in the ilert web interface:
Go to "Alert sources"
Click on "Add a new alert source"
Fill out the form chosing "API" as the integration type and save.
An integration key will be generated for the alert source after creation. You can obtain the key on the alert sources' details page. You can only use the key to post events to this alert source and you don't need to provide any other credentials when using the Event API.
Example: create, accept and resolve an alert
The following example will guide you through a basic workflow where an alert is created, accepted, and resolved.
Create alert
An alert can be created by posting an ALERT
event:
Request
https://api.ilert.com/api/events
{
"integrationKey": "edf0235f-a720-458e-a7fd-6b001042a4f4",
"eventType": "ALERT",
"alertKey": "srv/mail01",
"summary": "Host srv/mail01 is CRITICAL"
}
Let's say we want to post an update saying that the host is down. To do that, we will post another ALERT
event using the same alertKey:
Request
https://api.ilert.com/api/events
{
"integrationKey": "edf0235f-a720-458e-a7fd-6b001042a4f4",
"eventType": "ALERT",
"alertKey": "srv/mail01",
"summary": "Host srv/mail01 is DOWN"
}
Accept an alert
Continuing our example from above, we want to accept the alert that we created. In order to that, we post an ACCEPT
event using the same alertKey that we used when we posted the ALERT
event.
Request
https://api.ilert.com/api/events
{
"integrationKey": "edf0235f-a720-458e-a7fd-6b001042a4f4",
"eventType": "ACCEPT",
"alertKey": "srv/mail01"
}
The alert is now in ACCEPTED state stopping any further notifications.
Resolve an alert
To resolve the alert, we simply post a RESOLVE
event using the alert key from above.
Request
https://api.ilert.com/api/events
{
"integrationKey": "edf0235f-a720-458e-a7fd-6b001042a4f4",
"eventType": "RESOLVE",
"alertKey": "srv/mail01"
}
The alert is now resolved.
Dealing with errors and retries
We strongly recommend to implement a retry logic on the client side if an error occurs (ideally using an exponential backoff).
Retry a failed request for the following errors:
any network errors
5xx errors: this indicates an error in ilert
429 Too Many Requests: you have reached your rate limit
Do NOT retry a request for the following HTTP response codes:
202 Accepted: the request was successful
400 Bad Request: (check the error message for details)
the event type
The event summary. Will be used as the alert summary if a new alert will be created.
The event details. Will be used as the alert details if a new alert will be created.
Used to deduplicate events. If an open alert with the key already exists, the event will be appended to the alert's event log. Otherwise a new alert will be created. We will trim this value if necessary. Upper casing is allowed, however comparison is case insensitive.
Optional routing key that overwrites the escalation policy of the alert source for ALERT events. Must map to routingKey of escalation policy
POST /api/events HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 332
{
"integrationKey": "text",
"eventType": "ALERT",
"summary": "text",
"details": "text",
"alertKey": "text",
"priority": "HIGH",
"images": [
{
"src": "text",
"href": "text",
"alt": "text"
}
],
"links": [
{
"href": "text",
"text": "text"
}
],
"comments": [
{
"creator": "text",
"content": "text"
}
],
"customDetails": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"routingKey": "text"
}
The event has been accepted
No content
Was this helpful?