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

Introduction

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

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"
}
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.