Webhook Variables

When you write the body of your custom webhook, you can include static or dynamic key/value pairs.

The “root” object is notification, but it should not be referenced in the template. For example, to access the notification ID, use {{ id }} as the expression.

Variables Included

Variable	Type	Description
id	String	An identifier for the notification
type.id	Numeric	Clear (1) or Trigger (2)
alert.id	String	An identifier for the alert
alert.severity.id	String	The severity of the alert
alert.firstSeen.epochSecond	Date/time string	The time when the alert triggered
alert.firstSeen.epochMilli	Date/time string	The time when the alert triggered
alert.timeCleared.epochSecond	Date/time string	The time when the alert cleared
alert.timeCleared.epochMilli	Date/time string	The time when the alert cleared
alert.rule.id	String	An identifier for the alert rule
alert.rule.name	Numeric	Name of the alert rule
alert.rule.account.id	Numeric	An identifier for the account that owns the alert rule
alert.rule.account.organization.id	Numeric	An identifier for the organization that owns the alert rule
alert.rule.account.organization.timezone.id	String	An identifier for the organization’s time zone
alert.rule.expression	String	The machine-readable alert rule expression
alert.rule.notes	String	Alert rule notes
alert.rule.alertType.id	String	The alert rule’s alert type
alert.test.id	String	An identifier for the test that triggered the alert
alert.test.name	String	The name of the test that triggered the alert
alert.test.description	String	A description of the test that triggered the alert
alert.test.testType	String	The type of test that triggered the alert. For a list of test types, see ThousandEyes Test Types

The following variables are generic versions of concepts that might be called by other names depending on the alert type. For example, if the alerts are Cloud and Enterprise Agent alerts, details could refer to location alerts. If the alerts are BGP alerts, details might refer to monitors. Similarly, targets might refer to a URL or to a BGP prefix, for HTTP alerts or BGP alerts, respectively.

Note: agent, device, and outage alerts do not currently use targets.

Variable	Type	Description
alert.details.size	Numeric	Number of alert detail objects, such as agents or monitors, that triggered during the alert
alert.targets.size	Numeric	The number of target objects, such as URLs or prefixes, involved in the alert. This value is usually 1, except for agent-to-agent alert rules

Collections

Use a helper function, such as each, to iterate over collections of elements. The section headers below are the names of collections you can iterate over. The elements of each collection are listed in the tables in each section. Find example syntax in the Add Custom Webhook Integration interface by selecting the Generic preset.

Use syntax such as the following to iterate over the collection instance:

"test": {
            "name": "{{alert.test.name}}",
            "labels": [
                {{#each alert.test.labels}}
                    "{{name}}"{{#unless @last}}, {{/unless}}
                {{/each}}
            ]

When the collection has exactly one element, you can use syntax such as the following:

{{#if alert.targets.size}} 
  "targets": "{{#each alert.targets}}{{description}}{{#unless @last}}, {{/unless}}{{/each}}" 
{{/if}}

This will cause the targetName field to be populated correctly when there is one target on the alert, but avoids any errors if there are zero targets or more than one target on the alert.

Also note that all enumerations can be referenced by their ID, rather than their name. For example, the notification type can be referenced by 1 (for cleared notifications) or 2 (for triggered notifications), rather than the string “CLEAR” or “TRIGGER”, respectively. The advantage of doing this is that these underlying IDs will not change, whereas their names may change over time.

alert.details

Variable	Type	Description
metricsAtStart	String	The alert rule violations that triggered the alert
metricsAtEnd	String	The value of the metric when the alert cleared, for the metrics that were in violation when the alert triggered
source.id	Numeric	The identifier of the alert details' source. E.g., a VAgentID or MonitorID
source.ifIndex	Numeric	The interface index of the Device Interface instance. Available only for Device Test alerts.
source.name	String	The name of the alert details' source
state.id	Numeric	The alert detail's active state identifier: Clear (0), Trigger (1), Disabled (2).
asn.name	String	BGP only: The name of the AS associated with the source monitor

alert.targets

Variable	Type	Description
description	String	The name of the target

alert.test.labels

Variable	Type	Description
name	String	The name of the test label

Agent Notifications

These variables are only available to Agent Notifications:

Variable	Type	Description
alert.agent.id	String	An identifier for the agent
alert.agent.ipAddress	String	The IP address of the agent
alert.agent.name	String	The name of the agent
alert.agent.hostname	String	The hostname of the agent

Device Test

These variables are only available for Device Test alerts:

Variable	Type	Description
alert.device.id	String	An identifier for the device
alert.device.name	String	The name of the device

Device Notifications

These variables are only available for Device Notifications:

Variable	Type	Description
alert.resource.id	String	An identifier for the device resource
alert.resource.name	String	The name of the device resource

Linking to the Alerts List

Linking back to the ThousandEyes alerts list can be helpful for users who receive alert notifications. To provide a link in your webhook, navigate to Integrations. Select the Custom Webhook you'd like to edit. Scroll to the "Body" field and add the following url to the appropriate attribute:

https://app.thousandeyes.com/alerts/list/?__a={{alert.rule.account.id}}&alertId={{alert.id}}

Here is an example of adding the alerts list url to the text attribute of the default Slack template:

"text": "*Alert ID*: {{alert.id}}{{#if alert.test}}\n*Test Name*: {{alert.test.name}}\n*Target/s*: {{#each alert.targets}}{{description}}{{#unless @last}}, {{/unless}}{{/each}}{{/if}}\n*Alert Rule*: {{alert.rule.name}} - {{formatExpression alert.rule.expression}}{{#if alert.details}}\n*Details*: {{alert.details.size}}{{/if}}\n*Link*: https://app.thousandeyes.com/alerts/list/?__a={{alert.rule.account.id}}&alertId={{alert.id}}",

Helper Functions

The following helper functions are available to assist in templating. For a short tutorial on helper functions in the Handlebars framework, see the Handlebars guide.

• and

• each

• eq

• formatDate

• formatExpression

• gt

• gte

• if

• lt

• lte

• minus

• neq

• not

• or

• plus

• unless

• with

The helper functions formatDate and formatExpression are custom-built for alert notifications. The first takes a time variable such as alert.firstSeen and formats it into “YYYY-MM-DD HH:MM:SS Z” format, where Z is a timezone. The default timezone is UTC. You can use your organization’s timezone with the expression {{ formatDate alert.firstSeen alert.rule.account.organization.timezone }}, or you can hardcode a timezone like this:

{{ formatDate alert.firstSeen “America/Los_Angeles” }}

or

{{ formatDate alert.firstSeen “PST” }}

The formatExpression helper function converts a machine-readable alert rule expression such as ((responseTime > 100ms)) and translates it into a more human-readable format, such as Response Time > 100ms.

The plus helper function allows you to easily add two numeric values within your webhook payload. It's particularly useful for scenarios where you need to adjust numerical data, like aggregating totals or incrementing counters. For example, {{plus variable1 variable2}} would result in the sum of variable1 and variable2.

The minus helper function enables you to subtract one numeric value from another in your webhook payload. This is ideal for calculating differences, such as finding the delta in performance metrics. For example, use {{minus variable1 variable2}} to get the difference between variable1 and variable2.

Note: the data type of the variables will indicate the data type of the plus/minus result:

• int + int/int - int = int

• int + float/int - float = float