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

Yusof Yaghi

Updated October 26, 2022 15:58

Community moderator

Introduction

The purpose of this knowledge base article is to help guide you through Webhooks that were introduced within our CPM 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 CPMM 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	b5867e97-0952-4fbe-95ea-0d313170223e
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	CRITICAL
Status Color (hex)	`[(${statusColor})]`	Provides the HEX for the color of the type of Status.	#DD4B39
Category	`[(${category})]`	Provides the category selected when the monitor was created.	Endpoints
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	1636743066312
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	100
Consecutive Minutes	`[(${alertDurationMinutes})]`	The Duration (in minutes) of the issue when the monitor was triggered	30
Window (hours)	`[(${lookbackDurationHours})]`	The "Over the last" option under conditions - Generally not provided unless using Call Records.	4
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	100
Warn Threshold	`[(${warnThreshold})]`	The warn threshold number set under Conditions in Monitors	50
Info Threshold	`[(${infoThreshold})]`	The info threshold number set under Conditions in Monitors	10
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	100
Status Start Time (milliseconds)	`[(${statusStartTimeMs})]`	When the monitor has changed to that status in Epoch Time	636743066307
Created Time (milliseconds)	`[(${createdTimeMS})]`	The time the monitor was created in Epoch Time	636741066307
Created By Email	`[(${createdByEmail})]`	Email of the user that created the monitor	john.doe@vyopta.com
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	636743066307
Modified By Email	`[(${modifiedByEmail})]`	Email of the user that created the monitor	jane.doe@vyopta.com
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	10

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"
}