Skip to content
English
  • There are no suggestions because the search field is empty.

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:

  1. System device properties (%%DEVICE_ID%%, %%STATUS%%, and so on).
  2. Device and site variables (%%device.myVar%%, %%site.myVar%%).
  3. 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.

Notification Scope

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 Alerts

In 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

  1. Go to Settings → Alerts → HTTP Alerts and click Add.
  2. Enter an Alert Name (for example, Webhook - Job Summary) and select a Site (Global applies to all sites).
  3. Set Protocol to POST and enter the endpoint URL. Integration variables are supported.
  4. 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.