Document toolboxDocument toolbox

Working with alert definitions

Owned by Juan Tomás Alonso Nieto (Unlicensed)
Last updated: May 25, 2021 by Sarah Bigault (Deactivated)
12 min read

Add the following paths to your required endpoint to perform the operations defined below.

List all your alert definitions

Get the list of all the alerts defined in your domain using the following URL:

GET /v1/alertDefinitions

These are the parameters you can add to the URL to narrow down the required results:

ParameterTypeDefinition

page

Number

Use these parameters to group your list of alerts by a specific number (size) and get only one of the resulting groups (page). This comes in handy if you need to get only a specific set of alerts and have a long list.

Note that the count of both the selected page and groups defined starts at 0, so for example, if you enter page=2 and size=5 and have 22 alerts in your list, the API will divide the list into groups of 5 alerts (0-4, 5-9, 10-14, 15-19, and 20-22) and will return the group of alerts 10-14.

size

Number

nameFilter

String

Use this parameter to filter alerts by their names. You will only get alerts that contain the terms specified in their names. The filter is case insensitive.

idFilter

Number

Indicate an alert definition ID to get only that specific alert. 

Where can I get the ID of an alert definition?

You will get the ID of an alert definition after creating a new alert definition through the Alerting API (learn how to do it below). Note that this ID cannot be found in the Devo application.

Request examples

For example, this request will return the first group of up to 1000 alerts of your list of alert definitions in your domain:

https://api-us.devo.com/alerts/v1/alertDefinitions?page=0&size=1000

And this one will filter only alerts that include the term "security" in their names:

https://api-us.devo.com/alerts/v1/alertDefinitions?page=0&size=1000&nameFilter=security

Response example

This is the information that you will get for each alert in the requested list:

[
    {
        "id": "70736",
        "creationDate": 1604567644173,
        "name": "Alert_API_each",
        "message": "$eventdate $username - $count - API",
        "description": "Alert created by API",
        "categoryId": "7",
        "subcategory": "lib.my.testfake.AlertAPI_v660",
        "subcategoryId": "133",
        "isActive": true,
        "isFavorite": false,
        "isAlertChain": false,
        "alertCorrelationContext": {
            "id": "622",
            "nameId": "my.alert.testfake.Alert_API_each_Staging_1604567643224",
            "ownerEmail": "john@xx.com",
            "querySourceCode": "from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count",
            "priority": 5,
            "correlationTrigger": {
                "kind": "each"
            }
        },
        "actionPolicyId": []
    }
]

Create a new alert definition

Use the following URL to create a new alert definition in your domain:

POST /v1/alertDefinitions

You must specify the parameters of the new alert definition in the request body:

ParameterTypeDefinition

name*required

String

This should be a descriptive title for the alert and corresponds to the Alert name field in the New alert definition window of the Devo app.

message

String

A short message used to identify the alert condition. This text corresponds to the Summary field in the New alert definition window of the Devo app.

You can include the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger method to know the accepted fields.

description*required

String

The full description of the alert condition, which corresponds to the Description field in the New alert definition window of the Devo app. 

You can include in the alert description the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger method to know the accepted fields.

subcategory*required

String

This value corresponds to the Subcategory field in the New alert definition window of the Devo app. 

Alerts created by Devo users are always created under the My Alerts category. The value entered here is the subcategory you will use to group this alert.

alertCorrelationContext*required

Array

This array includes the following parameters:

  • querySourceCode*required  - Specify the LINQ query whose events will launch the type of alert defined.
  • priority*required - Enter the priority level of the alert defined. Values 1 to 10 are allowed, corresponding to the default values in the application:
    • Very low - 0, 1
    • Low - 2, 3
    • Normal - 4, 5
    • High - 6, 7

    • Very high - 8, 9, 10

      When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed here.

  • correlationTrigger*required - This array contains the type of alert you want to define and the specific parameters of that type. Use the parameter kind to enter the type of alert you want to define. Types correspond to the ones available in the Devo application, and are the following:

    • each

    • several
    • low
    • rolling
    • deviation
    • gradient

    Check the table below for the parameters you can include for each alert type.

Depending on the type of alert specified, you are allowed to include different parameters:

Alert typeParametersDescription
each--
severalperiod

Specify how frequently you want the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 1 second and the maximum value is 100 days.

threshold

Specifies how many events you want to use as a limit to trigger the alert.

It must be a positive integer number.

lowperiod

Specify how frequently you want the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 1 second and the maximum value is 100 days.

threshold

Specifies how many events you want to use as a limit to trigger the alert.

It must be a non-negative integer number.

rollingperiod

Specifies how frequently you want the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 60 seconds and the maximum value is 100 days.

backPeriodSpecifies how far in the past the search extends.
deviation

threshold

Specifies the proportions of the deviation from the median, in other words, the upper and lower bound that must be exceeded for an alert to be triggered. 

It must be a non-negative integer number.

absolute

Set this value to true if you want to use absolute values to calculate the deviation from the median, or false if you want to use a percentage.

Using an absolute value means that the threshold specified will be considered as the number above and below which the alert will be triggered. On the other hand, using a percentage means that the threshold specified will be considered as the percentage of the median value above and below which an alert will be triggered.

aggregationColumnSpecify an aggregation column whose values will be set against the designated threshold to trigger the alert. You can choose from any of the aggregation columns added to the query but you cannot add more than one.
gradientthreshold

Specifies the proportions of the deviation from the previous value, in other words, the upper and lower bound that must be exceeded for an alert to be triggered. 

It must be a non-negative integer number.

absolute

Set this value to true if you want to use absolute values to calculate the deviation from the median, or false if you want to use a percentage.

Using an absolute value means that the threshold specified will be considered as the number above and below which the alert will be triggered. On the other hand, using a percentage means that the threshold specified will be considered as the percentage of the median value above and below which an alert will be triggered.

aggregationColumnSpecify an aggregation column whose values will be set against the designated threshold to trigger the alert. You can choose from any of the aggregation columns added to the query but you cannot add more than one.

Learn more about each type of alert, their parameters, and how to set them in Alert trigger methods.

Request examples

Find below examples of the request body for each type of alert, including their specific parameters:

Each alert example
{
    "name": "myAlertEach",
    "message": "Alert definition message created with alerting API",
    "description": "Alert definition description created with alerting API",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where url = \"https://us.devo.com/alerts/view.json\"",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    }
}
Several alert example
{
    "name": "myAlertSeveral",
    "message": "Alert definition created with alerting API / Several",
    "description": "Alert definition long description / Several",
    "subcategory": "Subcategory/Several",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 3,
        "correlationTrigger": {
            "kind": "several",
            "period": 300000,
            "threshold": 10000
        }
    }
}
Low alert example
{
    "name": "myAlertLow",
    "message": "Alert definition created with alerting API / Low",
    "description": "Alert definition long description / Low",
    "subcategory": "Subcategory/Low",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 3,
        "correlationTrigger": {
            "kind": "low",
            "period": 300000,
            "threshold": 1
        }
    }
}
Rolling alert example
{
    "name": "Alert definition / Rolling",
    "message": "Alert definition created with alerting API / Rolling",
    "description": "Alert definition long description / Rolling",
    "subcategory": "Subcategory/Rolling",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every -",
        "priority": 4,
        "correlationTrigger": {
            "kind": "rolling",
            "period": 300000,
            "backPeriod": 3600000
        }
    }
}
Deviation alert example
{
    "name": "Alert definition / Deviation",
    "message": "Alert definition created with alerting API / Deviation",
    "description": "Alert definition long description / Deviation",
    "subcategory": "Subcategory/Deviation",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count",
        "priority": 5,
        "correlationTrigger": {
            "kind": "deviation",
            "threshold": 40,
            "absolute": true,
            "aggregationColumn": [ "count" ]
        }
    }
}
Gradient alert example
{
    "name": "Alert definition / Gradient",
    "message": "Alert definition created with alerting API / Gradient",
    "description": "Alert definition long description / Gradient",
    "subcategory": "Subcategory/Gradient",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count",
        "priority": 1,
        "correlationTrigger": {
            "kind": "gradient",
            "threshold": 40,
            "absolute": false,
            "aggregationColumn": [ "count" ]
        }
    }
}

Response example

This is an example of the response you get when you send a request to create a new alert definition. You will get the parameters indicated in the request plus the new alert ID, the creation date, and other useful information.

{
    "id": "70736",
    "creationDate": 1604567644173,
    "name": "Alert_API_each",
    "message": "$eventdate $username - $count - API",
    "description": "Alert created by API",
    "categoryId": "7",
    "subcategory": "lib.my.testfake.AlertAPI_v660",
    "subcategoryId": "133",
    "isActive": true,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
        "id": "622",
        "nameId": "my.alert.testfake.Alert_API_each_Staging_1604567643224",
        "ownerEmail": "john@xx.com",
        "querySourceCode": "from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    },
    "actionPolicyId": []
}

Update an alert definition

Add this path to your endpoint to update a specific alert definition in your domain.

PUT /v1/alertDefinitions

You must specify the parameters to be updated in the request body. Allowed parameters are the same ones as defined in the Create a new alert definition operation, plus an ID parameter to indicate the alert definition to be updated:

ParameterDefinition
id*requiredSpecify the ID of the alert definition that you want to update.

Non-editable parameters

Note that the name and subcategory parameters cannot be edited when you update an alert definition and must be left with their original values.

Request examples

This is a body example where we are modifying the message and description of an alert previously created:

{
    "id": "70736",
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where url = \"https://us.devo.com/alerts/view.json\"",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    }
}

And in this case, we are updating the same alert and transforming it into a Several type alert:

{
    "id": "70736"
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where username = "user@devo.com"",
        "priority": 3,
        "correlationTrigger": {
            "kind": "several",
            "period": 300000,
            "threshold": 10000
        }
    }
}

Response example

This is an example of the response you get when you update an alert definition. You will get the parameters indicated in the request plus the creation date, and other useful information.

{
    "id": "70736",
    "creationDate": 1604567644173,
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "categoryId": "7",
    "subcategory": "lib.my.testfake.AlertAPI_v660",
    "subcategoryId": "133",
    "isActive": true,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
        "id": "622",
        "nameId": "my.alert.testfake.Alert_API_each_Staging_1604567643224",
        "ownerEmail": "john@xx.com",
        "querySourceCode": "from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    },
    "actionPolicyId": []
}

Delete alert definitions in bulk

Use this operation to delete several alerts defined in your domain at the same time.

DELETE /v1/alertDefinitions

You only need to add the following parameter to the URL as many times as needed:

ParameterDefinition
alertIdsSpecify the ID of the alert definition(s) that you want to delete. You can add as many as you need.

Request example

In the following example, we are deleting a couple of alerts from our domain:

https://api-us.devo.com/alerts/v1/alertDefinitions?alertIds=0&alertIds=1

Update alert definition statuses in bulk

Use this operation to enable or deactivate several alerts at the same time. 

PUT /v1/alertDefinitions/status

You must indicate the IDs of the alerts to be updated and their new status by adding these parameters to the URL:

ParameterDefinition
alertIdsSpecify the ID of the alert definition(s) that you want to update. You can add as many as you need.
enableSet this parameter to true if you want to enable the alerts or false if you need to deactivate them.

Request example

In the following example, we are requesting to deactivate a couple of alerts from our domain:

https://api-us.devo.com/alerts/v1/alertDefinitions/status?alertIds=0&alertIds=1&enable=false