Skip to main content
Skip table of contents

Webhooks NQL examples

The NQL conditions field supports most of the syntax available in NQL. Nonetheless, this component cannot support the whole range of operators that NQL provides.

The main goal of this component is to declare the filters using NQL syntax for alerts or events that trigger a webhook.

Building the NQL conditions query

NQL tables

Tables supported by Webhooks

The official NQL syntax documentation states that the query should begin by specifying the name of the table to be used.

The list of tables that are allowed in the NQL conditions field are:

NQL Object

Valid in Webhook

alert.alerts

Yes

execution.crashes

Yes

device_performance.boots

Yes

device_performance.system_crashes

Yes

device_performance.hard_resets

Yes

remote_action.executions

Yes

Tables not supported by Webhooks

The list of tables that are not allowed in the NQL conditions field are:

NQL Object

Valid in Webhook

campaign.responses

No

campaign.campaigns

No

remote_action.executions_summary

No

session.logins

No

session.logouts

No

session.connects

No

session.disconnects

No

session.locks

No

session.unlocks

No

Punctual events

One characteristic that renders all the previous events unique is that they are all punctual events. This means that they occur at a specific point in time and do not have a span, as may be the case for other events such as applications.transactions

No error message will be displayed if you reference an NQL table other than what is listed above for the NQL Conditions field. The Webhook will be saved correctly and an error will only occur after the condition is evaluated. In the future, the component will be adjusted to display a message when an NQL table is not allowed to be used.

NQL operators

NQL Operators supported by Webhooks

Not all NQL operators are at the customer’s disposal. When working with punctual events, there is a subset of NQL operators that are valid.

NQL Operator

Type

Available in Webhook

where

selection

Yes

and

filtering

Yes

or

filtering

Yes

contains

filtering

Yes

in

filtering

Yes

Regardless of the type of NQL query that you are creating, it is important to pay attention to the table and the properties that can be used.

The list of fields for each of the tables allowed in the NQL conditions are listed below:

NQL Object

NQL property

Property Type

Operator

Example

alert.alerts

monitor.name

String

==, !=, in, !in

monitor.name == “Alert Name”
monitor.name !in “*Alert Name*”

monitor.multiple_contexts

Boolean

==, !=

monitor.multiple_contexts == true

monitor.priority

Enum

==, !=

monitor.priority == CRITICAL

monitor.tags

jsonArray

contains, !contains

monitor.tags contains “msteams”
monitor.tags !contains “splunk”

device_performance.boots

number_of_boots

Long

>, <, >=, <=, ==, !=

number_of_boots > 1

type

Enum

==, !=

type == FullBoot
type != FastStartup

device_performance.system_crashes

number_of_system_crashes

Long

>, <, >=, <=, ==, !=

count > 1

error_code

Long

>, <, >=, <=, ==, !=, in, !in

error_code == 239
error_code in [239,157]

label

String

==, !=, in, !in

label in [“CRITICAL”]
label !in [“DRIVER_POWER_STATE_FAILURE”]

execution.crashes

binary_path

String

==, !=, in, !in

binary_path !in [“/Netsuite/local”]

number_of_crashes

Long

>, <, >=, <=, ==, !=

number_of_crashes > 20

crash_on_start

Boolean

==, !=

crash.crash_on_start == true

remote_action.executions

remote_action.name

String

==, !=, in, !in

remote_action.name == “my-remote-action”

remote_action.name == “*remote-action”

remote_action.nql_id

String

==, !=, in, !in

remote_action.nql_id == “#my_remote_action”

status

Enum

==, !=

status in [expired , failure , cancelled ]
status == success

status_details

String

==, !=, in, !in

status_datails == “*some message*”

trigger_method

Enum

==, !=

trigger_method == api

purpose

Enum

==, !=

purpose == data_collection

request_id

String

==, !=, in, !in

request_id == “1e2bdd39-bb81-4c30-b985-41cdf49df7ef”

inputs

jsonArray

contains, !contains

intputs contains “msteams”
inputs !contains “splunk”

outputs

jsonArray

contains, !contains

outputs contains “msteams”
outputs !contains “splunk”

If you use an NQL table or field as part of a query that is not listed in the table above, it won’t be processed properly, even if its syntax is well written. In future, there will be more flexibility to incorporate more tables and fields into the NQL conditions editor.

NQL Operators not supported by Webhooks

Not all NQL operators are at the customer’s disposal. When working with punctual events, there is a subset of NQL operators that are not valid.

NQL Operator

Type

Available in Webhook

list

projection

No

with

association

No

compute … by

computation

No

limit

selection

No

sort … asc / desc

filtering

No

during past

selection

No

from … to …

selection

No

summarize

computation

No

summarize … by …

computation

No

last

computation

No

Examples of queries

Alerts

Valid NQL Queries

Trigger a webhook when a monitor named “MS Teams crashes in the last 24 hours" triggers an alert:

CODE
alert.alerts 
| where monitor.name == "MS Teams crashes in the last 24 hours"

Trigger a webhook when a monitor with high priority triggers an alert:

CODE
alert.alerts
| where monitor.priority == high 

Trigger a Webhook when a monitor named “MS Teams crashes in the last 24 hours" or “Poor video quality for computers" triggers an alert:

CODE
alert.alerts
| where monitor.name == "MS Teams crashes in the last 24 hours" 
or monitor.name == "Poor video quality for computers"  

Trigger a Webhook when a monitor with high priority or monitor named “MS Teams crashes for SD", and a tag that contains “servicenow" triggers an alert:

CODE
alert.alerts
| where monitor.priority == high
or monitor.name == "MS Teams crashes for SD"
and monitor.tags contains "servicenow"

Invalid NQL Queries

Invalid NQL tables and the wrong usage of the in operator:

CODE
device_performance.activities during past 7d
| where events.normalized_cpu_usage > 14 and monitor.tags in [*servicenow*]

Unavailable properties and the wrong usage of the in operator:

CODE
alert.alerts
| where trigger_time == "2021-10-23" and monitor.tags in ["*Logitech*"]

Unavailable operators:

CODE
devices
| with alert.alerts during past 7d 
| summarize c1 = count() by sid 

Events

Valid NQL Queries

Filter the device boots that are equal to fast_startup and when the duration is greater than 200 seconds:

CODE
device_performance.boots
| where type == fast_startup and duration > 200s

Filter the device crashes by error code 335 or 49 that refer to a timeout situation:

CODE
device_performance.system_crashes
| where error_code == 335 or error_code == 49 and label in ["TIMEOUT"]

Report all hard resets:

CODE
device_performance.hard_resets

Filter all the execution crashes for the binary zoom.exe that have crashed on start more than 5 times:

CODE
execution.crashes 
| where binary_path in ["zoom.exe"]
and number_of_crashes  >= 5 
and crash_on_start == true

Filter remote actions by nql_id and completed without a status [expired , failure , cancelled ]:

CODE
remote_action.executions
| where remote_action.nql_id == "#update_binary" 
and status in [expired , failure , cancelled ]

Invalid NQL Queries

Disallowed NQL tables:

CODE
devices
| with execution.crashes 
| where number_of_crashes >= 5 and device.operating_system.platform == Windows

Disallowed NQL operators:

CODE
devices
| with execution.crashes
| summarize count=count() by operating_system.name

Wrong value when comparing enums:

CODE
device_performance.BoOTS | where type == FULLboot
device_PErformance.BoOTS | where type == FULLboot
device_PErformance.BoOTS | where TyPe == FULLboot
device_performance . boots | where type == FullbooT

contains operator with empty values:

CODE
alert.alerts | where monitor.tags contains ""
alert.alerts | where monitor.tags !contains ""
alert.alerts | where monitor.name contains "BSOD"
alert.alerts | where monitor.thresholds contains "ratio_of_slow_pages"

RELATED TOPICS

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.