Last modified on September 12, 2018

AlertSite can send alerts in the JSON format to an external URL via an HTTP POST request. This is known as outgoing webhooks. You can use this to send alerts to your web servers or third-party services that accept incoming JSON data. For example, Slack integration uses JSON alerts with custom templates.

Considerations

  • If you are using AlertSite global locations, the target URL must be available on the public Internet.

  • Private locations support JSON alerts starting from v. 2.1.2.

  • Basic authentication is supported.

  • Adding custom HTTP headers is not supported.

Create a JSON POST recipient

In AlertSite UXM, go to Alerts > Alert Recipients (or Notifiers > Notifiers in AlertSite 1.0) and create a recipient of the POST JSON request to web server type.

Specify the target URL in the Recipient field. This URL must be available on the public Internet. Make sure to include http:// or https:// at the beginning of the URL.

If the target URL is protected with Basic authentication, specify the User and the Password.

Creating a JSON alert recipient

Click the image to enlarge it.

Once you create the recipient, edit it and choose whether it will receive availability alerts, performance alerts or both. For a description of the available settings, see Editing Recipients.

Alert data

Alerts contain information about the monitor and location that triggered the error, the error details, the date and time of the last check, and other details. By default, JSON alerts have the following format (see Alert Data Fields for the field descriptions).

Availability error

Availability "clear"

Performance error

Performance "clear"

Templates

You can change the field names and structure of JSON alerts by creating custom alert templates. There are separate templates for the “error” and “clear” alerts, availability, and performance alerts. The templates use variables to insert the monitor information into the alert.

Note: In order for custom templates to have effect, you need to either make these templates the default ones, or create a recipient group that combines the desired monitors, recipients and custom templates.

For an example of using custom templates, see Slack Integration and VictorOps Integration.

Availability template variables

The following variables care used in the Site Error and Site Clear templates.

Variable Description Example
$ALERT_NOTE Custom alert notes specified in the monitor settings. Maintenance is scheduled for this weekend.
$CERRORS The number of consecutive errors. 3
$COMPANY The AlertSite customer name, as seen on the  > Settings > Account screen in AlertSite UXM. SmartBear Software
$CUSTID The AlertSite customer ID, as seen on the  > Settings > Account screen in AlertSite UXM. C12345
$DESCRIP The monitor name. Home page
$DEVICE_ID The monitor ID. 13570
$DT_STATUS The date and time when the monitor was last checked, in the format YYYY-MM-DD hh:mm:ss. The timestamps in alerts use the time zone specified in your AlertSite settings. 2017-05-18 13:33:06
$DT_STATUS_GMT The UTC/GMT equivalent of the $DT_STATUS timestamp.

Note: This variable is available in ServiceNow templates only.

2017-05-18 18:33:06
$FULLIP The IP address the monitored server resolved to. 93.184.216.34
$GROUP_MEMBERS

If the alert was sent to a recipient group, this is a semicolon-delimited list of recipients in this group. Each recipient is in the format:

[Recipient Name - ]Recipient

The text in square brackets [ ] is optional and is included only if the recipient name is defined.

development@example.com; Operations - operations@example.com
$GROUP_NAME If the alert was sent to a recipient group, this is the name of the recipient group that triggered the current alert. Otherwise, an empty string. DevOps
$HTTP_STATUS The HTTP status of the monitor or of the failed step. HTTP/1.1 503 Service Unavailable
$ISTXN 1 for DéjàClick, SoapUI, Selenium and Perfecto Mobile monitors. 0 for other monitor types. 1
$LOC ID of the $LOCDESC location. 10
$LOCDESC The name of the AlertSite location that sent the alert. Note that depending on the monitoring mode, this may be not the same location that actually had the error. If rotated locations are used, those locations and their statuses are included in $RRDETAIL_ROWS. Fort Lauderdale, FL
$LOGIN The AlertSite login email of the account’s admin user. demo@example.com
$MSG The description of the AlertSite status code. HTTP error from web server
$NAME

The name of the failed step in a multi-step monitor (DéjàClick, Selenium, SoapUI, or Perfecto Mobile). An empty string otherwise.

Note: This variable is used in error templates only.

Customer Login
$NOTIFY_TYPE The message type: error, clear, test. error
$RRDETAIL_ROWS

This variable is specific to monitors that use rotated locations or were configured with the monitoring mode set to SLA (MultiPOP) or Round Robin. In other cases, the value of $RRDETAIL_ROWS will be empty.

$RRDETAIL_ROWS contains the monitor status at all locations used during the test interval. It is an array variable, which means the variable is replaced with the contents of the $RRDETAIL_ROWS template for each location. Multiple items are separated by commas.

The default $RRDETAIL_ROWS template is:

{
  "status": "$RROBJ_ERRNO",
  "status_text": "$RROBJ_LOC"
}

which expands to:

{
  "status": "7",
  "status_text": "HTTP error from web server",
  "location": "Fort Lauderdale, FL"
},
{
  "status": "0",
  "status_text": "Site responded normally to all tests",
  "location": "Atlanta, GA"
},
{
  ...
}

As another example, the following template:

"$RROBJ_LOC: $RROBJ_ERRNO - $RROBJ_ERRMSG"

expands to:

"Fort Lauderdale, FL: 7 - HTTP error from web server",+"Atlanta, GA: 0 - Site responded normally to all tests"

Note: The $RRDETAIL_ROWS variable is used in error templates only.

 
$SEQNO

The step number (from 1) of the failed step in a multi-step monitor. An empty string otherwise.

Note: This variable is used in error templates only.

3
$STATUS AlertSite status code. 0 means no errors. 7
$STATUS_LINK

Link to the run results in AlertSite.

Note: This variable is used in error templates only.

https://www.alertsite.com/cgi-bin/goevent?obj_devlog=12345678
$TYPE The monitor type as a one-letter code. See device_typecode for possible values. w
$TYPEPORT The monitor type. See device_type for possible values. Web Server
$URLLINE The monitored URL in web URL and API endpoint monitors. https://example.com

Variables used in the $RRDETAIL_ROWS template

$RROBJ_ERRMSG The description of the monitor status at this location. HTTP error from web server
$RROBJ_ERRNO The monitor status at this location. 7
$RROBJ_LOC The AlertSite location name. Fort Lauderdale, FL

Performance template variables

The following variables can be used in the Performance Error and Performance Clear templates. The Performance Error template applies to both performance errors and warnings.

Note: The $NOTIFY_TYPE, $MSG, and $STATUS variables mean the same thing (message type), just use different values for that.
Variable Description Example
$COMPANY The AlertSite customer name, as seen on the  > Settings > Account screen in AlertSite UXM. SmartBear
$CUSTID The AlertSite customer ID, as seen on the  > Settings > Account screen in AlertSite UXM. C12345
$DESCRIP The monitor name. Home page
$DEVICE_ID The monitor ID. 13570
$DT_STATUS The date and time the performance alert was triggered, in the YYYY-MM-DD hh:mm:ss format. The timestamps in alerts use the time zone specified in your AlertSite settings. 2017-05-18 13:33:06
$DT_STATUS_GMT The UTC/GMT equivalent of the $DT_STATUS timestamp.

Note: This variable is available in ServiceNow templates only.

2017-05-18 18:33:06
$METRIC ID of the response time metric used for performance alerting:
  • resptime – Response Time
  • resptime_fullpage – Fullpage Response Time
  • resptime_dns – DNS Time
  • resptime_connect – Connect Time
  • resptime_firstbyte – First Byte
  • resptime_content – Content Download
  • dejatime_domload – DOM Load
  • dejatime_pageload – Page Load
  • dejatime_firstpaint – First Paint
  • dejatime_aft – Above the Fold

Note: This variable is available in ServiceNow performance alert templates only.

resptime_fullpage
$METRIC_NAME The name of the response time metric used for performance alerting.

Note: This variable is available in ServiceNow performance alert templates only.

Fullpage Response Time
$MSG The message type – ERROR, WARN, or CLEAR. ERROR
$NAME If step-level performance alerts are configured for the monitor, this is the name of the step that triggered this performance alert. An empty string otherwise. Customer Login
$NOTIFY_TYPE The message type – perf_error, perf_warning, perf_clear. perf_error
$RESOURCE In monitor-level alerts, the value is Monitor. If step-level performance alerts are configured for the monitor, this is the name of the step that triggered the performance alert.

Note: This variable is available in ServiceNow performance alert templates only.

Login Step
$RRDETAIL_COUNT

The number of locations per interval used by this monitor. Individual locations are included in $RRDETAIL_ROWS.

Note: This variable is used in error templates only.

2
$RRDETAIL_ROWS

This variable contains the response time measurement for all locations used during the test interval. It is an array variable, meaning the variable is replaced with the contents of the $RRDETAIL_ROWS template for each location. Multiple locations are separated by commas.

The default template is:

{
  "perf_status": "$RROBJ_ERRNO",
  "perf_actual": "$RROBJ_ACTUAL",
  "perf_threshold": "$RROBJ_THRESHOLD",
  "perf_location": "$RROBJ_LOC",
  "perf_location_num": "$RROBJ_LOC_ID"
}

which expands to:

{
  "perf_status": "20",
  "perf_actual": "5.234",
  "perf_threshold": "4.500",
  "perf_location": "Austin, Texas",
  "perf_location_num": "63"
},
{
  "perf_status": "10",
  "perf_actual": "3.417",
  "perf_threshold": "2.500",
  "perf_location": "Dublin, Ireland",
  "perf_location_num": "5040"
},
{
  ...
}

Note: The $RRDETAIL_ROWS variable is used in error templates only.

 
$SEQNO

If step-level performance alerts are configured for the monitor, this is the step number (from 1) of the step that triggered the performance alert.

In monitor-level alerts, this is 0.

3
$SEVERITY Performance alert type:
  • 3 - error
  • 1 - warning
  • 0 - clear

Note: This variable is available in ServiceNow performance alert templates only.

3
$STATUS

The message type:

  • 20 – error
  • 10 – warning
  • 0 – clear
 
$STATUS_LINK

The link to the Performance Alert Report that visualizes the response time at each location compared to the error and warning thresholds.

Note: This variable is used in error templates only.

https://www.alertsite.com/rd/12345678

Variables used in the $RRDETAIL_ROWS template

$RROBJ_ACTUAL Current average response time at this location, in seconds. 4.706
$RROBJ_ERRMSG

The performance condition that this location observes:

  • ERROR
  • WARN
  • CLEAR (response time is within limits)

This value is not necessarily the same as $MSG.

WARN
$RROBJ_ERRNO

The performance condition that this location observes:

  • 20 – error
  • 10 – warning
  • 0 – no error (the response time is below the thresholds)

This value is not necessarily the same as $STATUS.

10
$RROBJ_LOC AlertSite location name. Fort Lauderdale, FL
$RROBJ_LOC_ID AlertSite location ID. See Monitoring Locations for possible values. 10
$RROBJ_THRESHOLD The response time threshold, in seconds, that is specified in the monitor settings. If $RROBJ_ERRNO is 20, this is the error threshold; otherwise, this is the warning threshold. 2.500

Test custom templates

Templates can be tested by sending a sample alert to a URL. You can use http://webhookinbox.com to create temporary URLs for testing and to inspect the data that comes in.

To test a template:

AlertSite UXM

  1. Go to Alerts > Template Editor.

  2. Select a template from the list, then click Send test.

    Note: If the Send Test button does not appear, click Close first.
    Test sample alert

    Click the image to enlarge it.

  3. Enter the URL to send the alert to and select a location.

    Test sample alert

    Click the image to enlarge it.

  4. If the target URL requires Basic authentication, enter the user name and password.

  5. Click Send.

AlertSite 1.0

  1. Go to Notifiers > Notifiers and click Manage Notification Templates.

    AlertSite 1.0: Manage Notification Templates

    Click the image to enlarge it.

  2. From the Message Type list, select one of the following:

    • Site Error via POST (JSON format) to view error templates

    • Site Clear via POST (JSON format) to view “all clear” templates

  3. Select a template from the list, then click Test Sample Alert.

    Test Sample Alert

    Click the image to enlarge it.

  4. Enter the URL to send the alert to, select a Location and click Send Message.

    The preview displays the JSON data that will be sent.

    Send test message

    Click the image to enlarge it.

See Also

Alert Templates
Alert Data Fields
Slack Integration

Highlight search results