Comment on page

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
  • neq
  • not
  • or
  • 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.