Variables in Alerts
Use Variables in Alerts in your Kilter instance.
Purpose
This article describes the variables you can use in HTTP Alerts in Kilter, where each one can be used, and the order in which Kilter substitutes them when an alert is sent. It includes step-by-step configuration and example use cases.
Overview
HTTP Alerts send an HTTP GET or POST request to an external system (a ticketing platform, a webhook, a monitoring tool) when a backup or task job completes. Variables are substituted at send time, so one alert template can be reused across many jobs and devices.
Four kinds of variables are available in alerts:
| Type | Syntax | Defined In | Where It Works |
|---|---|---|---|
| System device properties | %%UPPERCASE%% |
Populated by Kilter from the job result | POST body, Device scope only |
| Device variables | %%device.name%% |
Settings → Variables → Device Variables | POST body, Device scope only |
| Site variables | %%site.name%% |
Settings → Variables → Site Variables | POST body, Device scope only |
| Integration variables | %%INTEGRATION_VAR%% |
Integrations (ServiceNow, GLPI, Jira, and so on) | URL, headers, and body of GET and POST alerts (in the body for Device scope only) |
Go to Settings → Alerts and select the HTTP tab to configure HTTP Alerts.
Substitution Order
For POST alerts in Device scope, Kilter substitutes in this order:
- System device properties (
%%DEVICE_ID%%,%%STATUS%%, and so on). - Device and site variables (
%%device.myVar%%,%%site.myVar%%). - Any remaining
%%...%%patterns are matched against integration variables (%%SNOW_ITSM_INSTANCE_NAME%%, and so on).
The URL and the header values are substituted with integration variables only, before the body is built.
NOTE: Encrypted device and site variables are never substituted. The placeholder is left unchanged in the body.
System Device Properties
These values come from the job execution context. They are available only in POST alerts with Device scope.
| Variable | Description | Availability |
|---|---|---|
%%DEVICE_ID%% |
Internal Kilter device ID | Backup and Task jobs |
%%DEVICE_NAME%% |
Device display name | Backup and Task jobs |
%%DEVICE_EXTERNAL_ID%% |
External or integration ID of the device | Backup and Task jobs |
%%SITE_NAME%% |
Site the device belongs to | Backup and Task jobs |
%%SITE_ID%% |
Numeric site ID | Backup and Task jobs |
%%DEVICE_GROUP%% |
Device group name | Backup and Task jobs |
%%HOST%% |
Device IP address or hostname | Backup and Task jobs |
%%JOB_NAME%% |
Name of the backup or task job | Backup and Task jobs |
%%JOB_ID%% |
Numeric job ID | Backup and Task jobs |
%%JOB_TYPE%% |
BACKUP or TASK | Backup and Task jobs |
%%STATUS%% |
Execution result: success, failure, or suspect | Backup and Task jobs |
%%STATUS_REASON%% |
Explanation for the status | Backup and Task jobs |
%%CONFIGURATION_CHANGED%% |
Yes or No, whether a configuration change was detected | Backup jobs only |
%%BTN%% |
Backup Type Name: Vendor → Product → Version → Option | Backup jobs only |
Device Variables and Site Variables
Create device variables in Settings → Variables → Device Variables. Each variable has a name and a value for each device. Reference the variable in the alert body by its full name, for example %%device.ownerEmail%%. Kilter looks up the value for the device being reported. If a device has no value, the placeholder is replaced with an empty string.
Create site variables in Settings → Variables → Site Variables. A site variable holds one value for a site (or for all sites). Reference it as %%site.region%%.
Integration Variables
Integration variables come from the Integrations configuration. Their names are defined in the integration definition files in /backbox/conf/integrations/. They use the same %%VARIABLE_NAME%% syntax, are substituted last, and work in the URL, headers, and body.
Every HTTP POST alert has a Notification Scope that controls how it is sent and which variables apply to the body. GET alerts have no body and no scope.
| Scope | Body Template | Requests Sent | Variables Available In The Body |
|---|---|---|---|
| JOB | <<BackBox Text>> |
One per job execution | The full job JSON replaces <<BackBox Text>>. System, device, and site placeholders are not substituted. |
| DEVICE | %%VARNAME%%placeholders |
One per device in the job | System device properties, device and site variables, and integration variables |
NOTE: Choose JOB for a single summary per job run. Choose DEVICE to send a separate request per device, for example to open one ticket per failed device.
Job-Based AlertsIn Job scope, Kilter sends one POST per job execution. The <<BackBox Text>> token is replaced with raw JSON describing the job and the devices that match the notification filter (success, failure, or suspect).
Backup Job Payload
{
"BackBox_Backup": {
"id": 42,
"name": "Daily Router Backup",
"site_name": "HQ",
"status": "Success",
"devices": [
{
"id": 101,
"external_id": "RTR-HQ-01",
"name": "HQ-Core-Router",
"site_name": "HQ",
"device_group": "Core Routers",
"ip": "10.0.0.1",
"status": "success",
"status_reason": "",
"configuration_changed": "Yes",
"backup_type": "Cisco -> IOS -> 15.x -> Full"
}
]
}
}Task Job Payload
{
"BackBox_Task": {
"id": 55,
"name": "Weekly ACL Push",
"site_name": "Global",
"tasks": [
{
"id": 7,
"task_name": "Push ACL Rules",
"devices": [
{
"id": 101,
"external_id": "RTR-HQ-01",
"name": "HQ-Core-Router",
"site_name": "HQ",
"device_group": "Core Routers",
"ip": "10.0.0.1",
"status": "success",
"status_reason": ""
}
]
}
]
}
}NOTE: <<BackBox Text>> is replaced with raw JSON. Do not wrap it in quotes.
Configure A Job-Based HTTP Alert
Step 1: Create The Alert
- Go to Settings → Alerts → HTTP Alerts and click Add.
- Enter an Alert Name (for example,
Webhook - Job Summary) and select a Site (Global applies to all sites). - Set Protocol to POST and enter the endpoint URL. Integration variables are supported.
- Set Notification Scope to Job. The body fills in with
<<BackBox Text>>.
Step 2: Configure Headers. On the Headers tab, add at least one header, such as Content-Type: application/json.
Step 3: Configure The Body. Leave the body as <<BackBox Text>>, or wrap it in your own structure:
{
"source": "Kilter",
"payload": <<BackBox Text>>
}Step 4: Add The Alert To A Notification. Go to Notifications, create or edit a notification, add the alert on the HTTP Alerts tab, and choose which statuses trigger it.
Step 5: Assign The Notification To A Job. Edit the backup or task job, select the notification in the Notification field, and save.
Step 6: Test. On Settings → Alerts → HTTP Alerts, select the alert and click Test.
Device-Based Alerts
In Device scope, Kilter sends one POST per device that matches the status filter. Each request contains only that device's values.
Default Device Body Template
{
"id": "%%DEVICE_ID%%",
"device_name": "%%DEVICE_NAME%%",
"device_external_id": "%%DEVICE_EXTERNAL_ID%%",
"site_name": "%%SITE_NAME%%",
"site_id": "%%SITE_ID%%",
"device_group": "%%DEVICE_GROUP%%",
"host": "%%HOST%%",
"job_name": "%%JOB_NAME%%",
"job_id": "%%JOB_ID%%",
"job_type": "%%JOB_TYPE%%",
"status": "%%STATUS%%",
"status_reason": "%%STATUS_REASON%%"
}Extend the template with device and site variables:
{
"id": "%%DEVICE_ID%%",
"device_name": "%%DEVICE_NAME%%",
"status": "%%STATUS%%",
"region": "%%site.region%%",
"owner_email": "%%device.ownerEmail%%",
"snow_ci_id": "%%device.snowCiSysId%%"
}Configure A Device-Based HTTP Alert
If the body uses device or site variables, create them first under Settings → Variables and assign a value for each device or site. Do not mark them Encrypt, because encrypted variables are not substituted.
Go to Settings → Alerts → HTTP Alerts → Add, enter a name, set Protocol to POST, and enter the URL.
Set Notification Scope to Device. The body fills in with the device template.
Add headers on the Headers tab, and edit the body to match the receiving system.
Add the alert to a notification and enable the statuses that should trigger it (typically Fail and Suspect).
Assign the notification to the job, then use Test and run the job to confirm the substitution.
GET Alerts
GET alerts have no body. Variables work only in the URL and header values, and only integration variables are substituted. System device properties, device variables, and site variables are not available.
GET https://%%MONITORING_HOST%%/api/notify?source=Kilter&token=%%MONITORING_API_KEY%%
To configure one, set Protocol to GET, enter the URL with any integration variables, add headers if needed, and add the alert to a notification assigned to a job.
Authentication And Headers
On the Toggles tab, turn on Enable Authentication, then enter a Username and Password. Kilter sends Authorization: Basic <Base64(username:password)> automatically, in addition to your custom headers. Use this toggle for Basic Auth instead of building the header by hand.
Custom header values are substituted with integration variables, for example Authorization: Bearer %%MONITORING_API_KEY%%. A header value is sent exactly as written after substitution, so a Basic header typed by hand must already contain the Base64-encoded credentials.
Auditing Options
| Toggle | Behavior |
|---|---|
| Enable HTTP Auditing | The alert also fires for audit events (logins, configuration changes), not only for backup and task completions. |
| Append Auditing Details | Adds a readable audit detail string to the message. Only meaningful when Enable HTTP Auditing is on. |
Auditing alerts use Job scope behavior: one message per event, with no per-device loop.
Example Use Cases
1. Open One ServiceNow Incident Per Failed Device
Use a POST alert in Device scope, and enable only Fail and Suspect in the notification. Turn on Enable Authentication with a ServiceNow service account.
URL: https://%%SNOW_ITSM_INSTANCE_NAME%%.service-now.com/api/now/table/incident
{
"short_description": "Kilter: %%DEVICE_NAME%% %%JOB_TYPE%% %%STATUS%%",
"description": "Device: %%DEVICE_NAME%%\nIP: %%HOST%%\nJob: %%JOB_NAME%%\nReason: %%STATUS_REASON%%",
"cmdb_ci": "%%device.snowCiSysId%%",
"u_site": "%%site.region%%",
"category": "Network",
"urgency": "2"
}2. Post A Job Summary To A Chat Webhook
Use a POST alert in Job scope so the channel receives one message per job run, with every matching device in the payload.
{
"source": "Kilter",
"payload": <<BackBox Text>>
}3. Route Alerts By Region Or Owner
Create a site variable %%site.region%% and a device variable %%device.ownerEmail%%, then include them in a Device scope body. The receiving system can use these fields to assign the ticket to the right team without separate alerts per site.
4. Notify A Monitoring Tool With A GET Request
Store the monitoring host and API key as integration variables, and reference them in the URL of a GET alert, as in the GET example above. Keep the key in the integration configuration so it does not appear in the alert definition.
5. Flag Only Configuration Changes
For a backup job in Device scope, include %%CONFIGURATION_CHANGED%% and %%BTN%% in the body so the receiving system can filter on Yes and record the device type.
Tips
- Send only on failure. In the notification, enable only Show Failures.
- Handle empty values. A device variable with no value for a device resolves to an empty string. Design the receiving side to accept empty fields.
- Secrets. Store tokens as integration variables. Device and site variables marked Encrypt are skipped during substitution.
- Reuse. One HTTP alert can be used by many notifications. The URL, headers, and body are shared, and only the substituted values change.
Variable Syntax Quick Reference
| Context | Syntax | Example |
|---|---|---|
| System device property (Device scope body) | %%UPPERCASE%% |
%%STATUS%%, %%JOB_TYPE%% |
| Device variable | %%device.name%% |
%%device.snowCiSysId%% |
| Site variable | %%site.name%% |
%%site.region%% |
| Integration variable | %%INTEGRATION_VAR_NAME%% |
%%SNOW_ITSM_INSTANCE_NAME%% |
| Job scope payload | <<BackBox Text>> |
Replaced with the job JSON |
Related Articles
If you need additional information, contact support@backbox.com.