How To: Write a Custom Monitor Webhook - Syntax and Variables


The purpose of this knowledge base article is to help guide you through Webhooks that were introduced within our Tech Insights Monitoring - Monitors Notification.

Webhooks allow you as a user to send triggered monitor notifications directly to any system that is publicly accessible to either generate tickets, create chat alerts or run automation!


Understanding the Syntax

Webhooks under Tech Insights Monitoring Monitors follows the JSON standard, however, to allow customization, a few basic functions were created that can be inserted into the JSON document. Which we will walk through below:


Provided Syntax are:

  Quick Examples
System Variables {[(${alertId})]
If Statement [# th:if="${VARIABLE}" ]
Unless [# th:unless="${VARIABLE} == 0" ]
Inline If Else

[(${VARIABLE} ?: 'Not specified')]


Syntax Walkthrough

System Variables:

System variables are variables from the Vyopta cloud that are used to fill in data about the alert. This is used to provide data about the alert when it's sent out to your system/messaging app.

Variable Name Variable ID Description Example
ID [(${alertId})] This provides the Alert ID


Name [(${name})] Alert Name which is set when creating the Monitor (Monitor Name) Test Monitor
Description [(${description})] Provides a description of the monitor configuration

Endpoint in ( System1 )

Status [(${status})] Provides the Status of the Monitor. Either CRITICAL, WARN, INFO


Status Color (hex) [(${statusColor})] Provides the HEX for the color of the type of Status.


Category [(${category})] Provides the category selected when the monitor was created.


Metric [(${metric})] Provides the Metric selected when the monitor was created.

In Call Count

Fired Time (milliseconds) [(${alertFiredTimeMs})] This is the Time the Monitor was Triggered. This is provided in Epoch Time


Operation [(${operation})]

This is the "Triggered when metric is" which is in the "Set alert conditions" on the monitors page.

The options are:

  • Greater Than or Equals
  • Greater Than
  • Less Than
  • Less Than or Equals
  • Equals
  • Not Equals

equal to

Threshold [(${threshold})]

The threshold that was triggered for either Critical, Warn and Info 


Consecutive Minutes [(${alertDurationMinutes})]

The Duration (in minutes) of the issue when the monitor was triggered


Window (hours) [(${lookbackDurationHours})]

The "Over the last" option under conditions - Generally not provided unless using Call Records.


Url [(${alertUrl})]

A URL that takes your directly to the monitor that has been triggered with the timestamp marker as a vertical line 


Critical Threshold [(${errorThreshold})]

The critical threshold number set under Conditions in Monitors


Warn Threshold [(${warnThreshold})]

The warn threshold number set under Conditions in Monitors


Info Threshold [(${infoThreshold})]

The info threshold number set under Conditions in Monitors


Selected Items [(${selectedItems})]

Provides the names of the selected items in the monitor. Comma Delimited

System1, System2

Item Count [(${deviceCount})]

Provides a count of the selected items in the monitor


Status Start Time (milliseconds) [(${statusStartTimeMs})]

When the monitor has changed to that status in Epoch Time


Created Time (milliseconds) [(${createdTimeMS})]

The time the monitor was created in Epoch Time


Created By Email [(${createdByEmail})]

Email of the user that created the monitor

Created By Name [(${createdByName})]

Name of the user that created the monitor

John Doe

Modified Time (milliseconds) [(${modifiedTimeMs})]

The time the monitor was last modified in Epoch Time


Modified By Email [(${modifiedByEmail})]

Email of the user that created the monitor

Modified By Name [(${modifiedByName})]

Name of the user that last modified the monitor

Jane Doe

Clear Duration (minutes) [(${okDurationMinutes})]

When a Clear status is sent, this will indicate in minutes how long the issue has been in that state



Functions in Body:

To allow flexibility, Functions were introduced in the Webooks section. This allows the user to tweak what data should be sent.

If Statement:

There may be an occasion you would want to perform an if statement. 

Below is an example of displaying "Critical Threshold is X" if the "errorThreshold" variable is being sent

[# th:if="${errorThreshold}" ], {
"Critical Threshold is [(${errorThreshold})]"


Unless Statement:

The unless statement is as simple as the if statement mentioned above. Some variables will always exist, however provide a number of 0. 


In the example below, we are going to display a message unless "Clear Duration Minutes" is equal to 0.

[# th:unless="${clearDurationMinutes} == 0" ], {
"[(${clearDurationMinutes})] minutes"


Inline If Else:

Inline If Else can be used to quickly check if a variable exists and replace it with a message of your own. 

An example of the inline If statement to check if the "Critical Threshold" was specified and if not, replace it with "Not specified" can be done like this:

[(${criticalThreshold} ?: 'Not specified')]


Webhook Headers

Webhooks also allows headers to be configured in the body of the webhook. When a header is needed, it needs to be entered before the JSON and with a line break in between.

Multiple headers can be set to be passed onto the remote server.

Example headers are:

  • Content-Type
  • Authorization

Below is an example of using the Content-Type and Authorization Headers to send a Webex message:

Content-Type: application/json
Authorization: Bearer <Token>

"roomId": <Webex RoomId>,
"markdown": "This will be sent as a message"
Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.