Webhooks NQL examples

The NQL conditions configuration field within Webhooks supports most of the syntax available in NQL. However, Webhooks is limited to a set of NQL tables, properties and operators.

NQL tables supported by Webhooks

The NQL syntax overview documentation states that the query should begin by specifying the table name: <namespace>.<table>

Find below the supported NQL tables for webhooks.

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

Refer to the NQL properties supported by Webhooks section on this page for the specific NQL table fields.

Webhooks only supports the NQL tables in the format of <namespace>.<table> listed above. The system may display an error message when saving a webhook configuration with unsupported NQL objects in the NQL conditions field.

NQL operators supported by Webhooks

Not all NQL operators are at the customer's disposal. When working with punctual events, use the following subset of NQL operators.

NQL Operator	Type	Available in Webhook	Mandatory
`where`	selection	Yes	Yes, at least once.
`list`	projection	Yes	Yes, at least once.
`and`	filtering	Yes	No
`or`	filtering	Yes	No
`contains`	filtering	Yes	No
`in`	filtering	Yes	No

NQL properties supported by Webhooks

Find below the list of fields for each of the supported NQL tables for webhooks.

Remember, using unsupported NQL table fields results in system errors, even for valid syntaxes.

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`	`type`	Enum	`==`, `!=`	`type == FullBoot` `type != FastStartup`
`device_performance.system_crashes`	`error_code`	Long	`>`, `<`, `>=`, `<=`, `==`, `!=`, `in`, `!in`	`error_code == 239` `error_code in [239,157]`
`device_performance.system_crashes`	`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"`

Valid NQL query examples for Webhooks

Some of these valid NQL query examples assume you previously defined the associated alerts. Refer to the Getting started with Alerts documentation for more information.

Valid NQL example.1 - 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"
| list alert.context

Valid NQL example.2 - Trigger a webhook when a monitor with high priority triggers an alert.

CODE

alert.alerts
| where monitor.priority == high
| list alert.context

Valid NQL example.3 - 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"
| list alert.context

Valid NQL example.4 - 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"
| list alert.context

Valid NQL example.5 - 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
| list device_performance.boot.type, device_performance.boot.duration

Valid NQL example.6 - 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"]
| list device_performance.system_crash.error_code

Valid NQL example.7 - 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
| list execution.crash.number_of_crashes

Valid NQL example.8 - 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 ]
| list remote_action.execution.outputsInvalid NQL query examples for Webhooks

Invalid NQL query examples for Webhooks

Some of these invalid NQL query examples assume you previously defined the associated alerts. Refer to the Getting started with Alerts documentation for more information.

Invalid NQL example.1 - Unsupported NQL tables, missing the list operator and wrong usage of the in operator.

CODE

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

Invalid NQL example.2 - Unavailable properties and the wrong usage of the in operator.

CODE

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

Invalid NQL example.3 - Unavailable operators.

CODE

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

Invalid NQL example.4 - Unsupported NQL tables.

CODE

devices
| where device.operating_system.platform == Windows
| list device.name

Invalid NQL example.5 - Unsupported NQL operators.

CODE

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

Invalid NQL example.6 - 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

Invalid NQL example.7 - 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"