Events

Post an event to ilert.

post

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 ACCEPTevent)

• a problem is resolved (a RESOLVEDevent)

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:

Attribute	Description
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.
severity	Optional. Must be an integer in range 1..5. Will overwrite the evaluated severity of the alert source.
services	Optional. A list of service objects, each containing an alias.
labels	Optional. A map of key/value labels attached to the alert.
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:

1. Go to "Alert sources"

2. Click on "Add a new alert source"

3. 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 ACCEPTevent 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)

Body

application/json

integrationKeystringRequired

eventTypestring · enumRequired

the event type

Possible values:

summarystringRequired

The event summary. Will be used as the alert summary if a new alert will be created.

detailsstringOptional

The event details. Will be used as the alert details if a new alert will be created.

alertKeystringOptional

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.

prioritystring · enumOptionalPossible values:

severityinteger · int32 · min: 1 · max: 5Optional

Optional severity in range 1..5. Will overwrite the evaluated severity of the alert source.

routingKeystringOptional

Optional routing key that overwrites the escalation policy of the alert source for ALERT events. Must map to routingKey of escalation policy

Responses

202

The event has been accepted

post

/events

HTTPcURLJavaScriptPython

POST /api/events HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 426

{
  "integrationKey": "text",
  "eventType": "ALERT",
  "summary": "text",
  "details": "text",
  "alertKey": "text",
  "priority": "HIGH",
  "severity": 1,
  "images": [
    {
      "src": "text",
      "href": "text",
      "alt": "text"
    }
  ],
  "links": [
    {
      "href": "text",
      "text": "text"
    }
  ],
  "comments": [
    {
      "creator": "text",
      "content": "text"
    }
  ],
  "labels": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "services": [
    {
      "id": 1,
      "alias": "text"
    }
  ],
  "customDetails": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "routingKey": "text"
}

202

The event has been accepted

No content