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:
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:
- Navigate to Application>Settings>Webhooks page in cnMaestro UI
2. Click Add Webhook. The following window appears:
- 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.
This will display the response Code, Headers and Body from Webhook endpoint.
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