Integration of Webhooks with cnMaestro

Summary:

     cnMaestro Webhooks provide real-time streaming for Alarms using a push notification model. Webhooks enable integration with external cloud services, such as Slack, Twilio, Zapier, Datadog, PagerDuty, etc. They can also be supported using a local HTTPS server and custom applications. Once configured, cnMaestro streams alarms to these services over HTTPS to the configured URL. All requests are sent over HTTPS for security, and the server certificate is validated by default. Some example services are presented below:

fig 1 Webhook integration with external cloud services.png

The Webhook payload is sent in a JSON or a URL-encoded format, and the parameters are comparable to the alarm details present in the RESTful API and email notifications. In addition, cnMaestro also provides default and custom Webhooks templates, so the data format can be tailored to specific services.

cnMaestro Webhooks Configuration:

To create a Webhook:

  1. Navigate to Application>Settings>Webhooks page in cnMaestro UI

fig 5 webhooks table.PNG   

      2. Click Add Webhook. The following window appears:

fig 2 configure Add webhook parameters page.PNG

  1. Enter the parameters
  • Name and URL: Webhook label for display and filtering purposes. This will also be included in the default payload as Webhook_name. The URL defines the endpoint for the HTTPS POST request. Only HTTPS is supported.
  • Managed Account: If cnMaestro is configured for MSP (Managed Service Provider), you can map the Webhook to a Managed Account.  A maximum of two Webhooks can be configured per Managed Account.
  • Type: Type of cnMaestro notification to configure Webhook.(Note: cnMaestro release 2.3.x supports only alarms as the type for Webhook configuration.)
  • Basic Authentication: Optionally add https basic authentication to the Webhook POST request. By enabling basic authentication, you can configure the username and password associated with your endpoint. The basic authentication parameters are base64 encoded and included in the header of the HTTP request. 

Note 1: The username and password for basic authentication are different from cnMaestro user credentials. These credentials are used at your endpoint, few external integrations like Slack only require Webhook URL, for integrations where basic authentication is not required.

 

Note 2: Basic authentication is an HTTP standard which adds an “Authorization: Basic <credentials>” header to the HTTPS POST request. Credentials are Base64 encoded username and password, encoded the following way: Base64(username: password)

  • Filters: the filters support filtering alarms based on severity such as Minor, Major, or Critical And Device types from the drop-down list.
  • Advanced Configuration: content-type can be JSON or URL-Encoded Form. cnMaestro supports default and custom templates for the payload. Custom templates allow specialized payload formats. Enable the Custom checkbox and upload your own custom payload JSON.

Types of variables:

The following variables can be used to specify your own payload within a custom template. The variables will be replaced with actual values before sending to Webhook endpoint.

Variable

Description

$ACKNOWLEDGED_BY

Alert acknowledged by

$ALARM_DURATION

Alarm duration (seconds)

$ALARM_ID

Alarm ID (e.g. 9bd4Gc313a4d1e8fie2482df7b77628)

$ALARM_MSG

Alarm message (e.g.: “GPS Sync state changed to Synchronized”)

$ALARM_NAME

Alarm name (e.g.: Configuration Sync)

$ALARM_SEVERITY

Alarm severity (e.g. critical, major, minor)

$ALARM_STATUS

Alarm status (e.g. active)

$ALARM_TIME_RAISED

Alarm raised time (ISO 8601 Date format: 'YYYY-MM- DDTHH:mm:ssZ')

$ALERT_CODE

Alert code (e.g. STATUS)

$DEVICE_MAC

Device MAC address (ex: AA:BB:CC:DD:EE:FF)

$DEVICE_MODEL

Device MAC Model (ex: ePMP 1000, cnPilot r201)

$DEVICE_NAME

Device name

$DEVICE_IP

Device IP Address (ex: 192.168.0.1)

$DEVICE_TYPE

Device type (e.g.Wi-Fi-enterprise)

$MANAGED_ACCOUNT

Managed account name (absent if not mapped to an account)

$NETWORK_NAME

Network name

$SITE_NAME

Site name (note: value will be blank if the device is not under a Site)

$TOWER_NAME

Tower name (note: 'value will be blank if the device is not under a Tower')

$WEBHOOK_NAME

Webhook name

$WEBHOOK_RETRY_COUNT

Retry count (note: only present if Webhook is retried; default is 0)

$WEBHOOK_TIMESTAMP

Webhook sent time (ISO 8601 Date format: 'YYYY-MM- DDTHH:mm:ssZ')

The default format is kept consistent with RESTful API alarms format as follows.

{

"ip" :  "$device_ip",

"network" :   "$network_name",

"message" :   "$alarm_msg",

"name" :   "$alarm_name",

"severity" :   "$alarm_severity",

"source_type" :   "$device_type",

"source_model" :   "$device_model",

"status" :   "$alarm_status",

"time_raised" :   "$alarm_time_raised",

"site" :   "$site_name",

"duration" :   "$alarm_duration",

"id" :   "$alarm_id",

"code"  :   "$alert_code",

"mac" :   "$device_mac",

"acknowledged_by" :   "$acknowledged_by",

"source"  :   "$device_name",

"managed_account" :   "$managed_account"

"webhook_retry_count" :   "$webhook_retry_count",

"webhook_timestamp" :   "$webhook_timestamp ",

"webhook_name" :   "$webhook_name" 

}

Error and Retransmission:

cnMaestro expects an HTTP status code 2XX reply from the configured Webhook URL to confirm the alarm notification sent via HTTPS POST has been successfully delivered. For any request, if status code 5XX is received, cnMaestro will keep retrying the same payload at the interval of 1, 2, 5, 10, 15 and every 15 minutes thereafter until the request succeeds. 3XX or 4XX response will not be retried.

Note: If there are multiple webhooks configured, a retry/error on the one webhook will not affect the other. For example, if you have Zapier and Twilio, a retry/error on the Twilio will not affect the Zapier, any new alarm notification on Twilio will be discarded and a retry will happen only with the cached payload.

Status check:

The last sent message’s response can be checked by clicking View Details.

fig 6 last status.png

This will display the response Code, Headers and Body from Webhook endpoint.                        

fig 7 last response.PNG

Explore more about Webhook Integration with External Cloud Services:

Configuration of Slack with cnMaestro Webhooks

Configuration of Datadog with cnMaestro Webhooks

Configuration of Pagerduty with cnMaestro Webhooks

Configuration of Twilio with cnMaestro Webhooks

Configuration of MS Teams with cnMaestro Webhooks

12 Likes