.Working with alert definitions vv7.3.0

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:

Parameter	Type	Definition
`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:

Parameter	Type	Definition
`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`	JSON	This JSON object 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 type	Parameters	Description
`each` The parameters for the `each` type alerts are mandatory if the specified query includes subqueries. However, not every query containing a subquery is allowed. Learn more about this in this section.	`externalOffset`	It is used to move the main query time range backward in time. It must be expressed in milliseconds. For example: if the main query time range is `[now()-1h, now()]` with an `externalOffset` of 2 days, the time range would be `[now() -1h -2d, now() - 2d]` The maximum time range allowed is 8640000000 milliseconds (up to 100 days).
	`internalPeriod`	It is used to set the subquery time range. It must be expressed in milliseconds. For example: for an `internalPeriod` of 10 days, the subquery time range would be `[now() - 10d, now()]` The minimum allowed temporal 60000, and the maximum is 8640000000 (from 1 min to 100 days).
	`internalOffset`	It is used to move the subquery time range backward in time. It must be expressed in milliseconds. For example: if the subquery time range is `[now()-10d, now()]` with an `internalOffset` of 2 days, the time range would be `[now() -12d, now() - 2d]` The maximum time range allowed is 8640000000 milliseconds (up to 100 days).
`several`	`period`	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.
`several`	`threshold`	Specifies how many events you want to use as a limit to trigger the alert. It must be a positive integer number.
`low`	`period`	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.
`low`	`threshold`	Specifies how many events you want to use as a limit to trigger the alert. It must be a non-negative integer number.
`rolling`	`period`	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.
`rolling`	`backPeriod`	Specifies 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.
	`aggregationColumn`	Specify 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.
`gradient`	`threshold`	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.
	`aggregationColumn`	Specify 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.

Defining alerts with queries that include subqueries

As specified in the required parameters for the each-type alert above, users can generate alerts based on queries that contain subqueries by adding some required extra parameters. However, not every query is allowed.

Take the following into account when defining your source query:

Queries must not include nested subqueries.
Queries must not include a fixed time range in the subquery.
Queries must not include a temporal grouping in the subquery.
my.lookuplist tables cannot be used in subqueries. Learn more about lookups in Data enrichment.

See the following table to check examples of valid and not allowed query formats:

Query	Allowed?
`from T1`	This query does not include any subquery, so it is not allowed.
`from T1` `where x in (` `from T2` `where y in (` `from T3` `)` `)`	This query includes nested subqueries, so it is not allowed.
`from T1` `where x in (` `from T2` `where 100 <= eventdate < 200` `)`	This query includes a fixed time range in its subquery, so it is not allowed.
`from T1` `where x in (` `from T2` `group every 10m` `)`	This query includes a temporal grouping in its subquery, so it is not allowed.
`from T1` `where x in (` `from T2` `)`	This query has neither a group nor a time range in its subquery, so it is allowed.
`from T1` `group by x every 10m` `where x in (` `from T2` `)`	This query has a temporal grouping, but it is not included in the subquery. Therefore, it is allowed.

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"
        }
    }
}

Each alert example with subquery

{
    "name": "Alert definition with sub query",
    "message": "Alert definition with sub query",
    "description": "Alert definition with sub query",
    "subcategory": "Subcategory/Each",
    "alertCorrelationContext": {
        "querySourceCode": from siem.logtrust.web.activity where eq(url, \"https://us.devo.com/home\"), eq(type, \"request\") where username in (from siem.logtrust.web.activity where eq(url, \"https://us.devo.com/m2search\"), eq(type, \"request\") select username) select username, userid, sessionid, locale, userAgent
        "priority": 1,
        "correlationTrigger": {
            "kind": "each",
            "externalOffset": 0,
            "internalPeriod": 60000,
            "internalOffset": 1000
        }
    }
}

Each alert example

{
    "name": "Alert definition without subquery",
    "message": "Alert definition with subquery",
    "description": "Alert definition with subquery",
    "subcategory": "Subcategory/Each",
    "alertCorrelationContext": {
      "querySourceCode": "from siem.logtrust.web.activity group every 30m by url every 1h select count() as count",
      "priority": 1,
      "correlationTrigger": {
        "kind": "each",
        "externalOffset": 0,
        "internalPeriod": 60000,
        "internalOffset": 1000
      }
   }
}

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:

Parameter	Definition
`id^*required`	Specify 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:

Parameter	Definition
`alertIds`	Specify 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:

Parameter	Definition
`alertIds`	Specify the ID of the alert definition(s) that you want to update. You can add as many as you need.
`enable`	Set 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

List all your alert definitions

GET /v1/alertDefinitions

Request examples

Response example

Create a new alert definition

POST /v1/alertDefinitions

Defining alerts with queries that include subqueries

Request examples

Response example

Update an alert definition

PUT /v1/alertDefinitions

Request examples

Response example

Delete alert definitions in bulk

DELETE /v1/alertDefinitions

Request example

Update alert definition statuses in bulk

PUT /v1/alertDefinitions/status

Request example

`GET /v1/alertDefinitions`

`POST /v1/alertDefinitions`

`PUT /v1/alertDefinitions`

`DELETE /v1/alertDefinitions`

`PUT` `/v1/alertDefinitions/status`