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.Variable | Type | Description |
id | Numeric | 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 | Numeric | 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 |
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.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 |
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.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 |
Variable | Type | Description |
description | String | The name of the target |
Variable | Type | Description |
name | String | The name of the test label |
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 |
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 |
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 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}}",
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.
andeacheqformatDateformatExpressiongtgteifltlteneqnotorunlesswith
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.