Webhook Notifier

The Webhook Notifier sends notifications using HTTP POST using a JSON body. The handler emits all available information about the alarm to the recipient, which is expected to parse the message and correlate it with other messages. The alarm_id can be used for correlation to see which notifications belong together; if they have the same alarm_id they are considered state changes on the same alarm. The notification has a timestamp last_updated which can be used in the event of notifications arriving out of order.

There are two available message formats:

  • flat : A key-value map where all values are strings
  • nested : A key-value map where each value can be a nested map

The following keys are used in the flat and nested formats:

Key Description
alarm_id A unique identifier for the alarm
alarm_type The type of alarm. Eg failed-authentication
resource_id The ID of the configured resource raising the alarm
resource_type The Type of the configured resource raising the alarm
node_id The ID of the node the alarm was raised on
cleared The current clearance status
severity The severity of the alarm
dashboard_link A link to the alarm in the admin web UI
brief_description A short description of the alarm
detailed_description A more detailed description of the alarm
impacted_resources A list of resources per type, impacted by the alarm
suggested_actions A list of actions suggested to take to mitigate the alarm
last_updated The time the alarm was last updated, in ISO-8601 format

Note

The same alarm_id will be used for notifications concerning the same alarming resource and alarm type. If the state changes from cleared = true to cleared = false or if the severity is changed, a new notification is sent with the same alarm_id.

Flat Format

The flat format is limited to a single level in the json map. Long strings may contain newline characters which the recipient system must parse for readability.

{
    "alarm_id" : "<STRING>",
    "alarm_type" : "<STRING>",
    "resource_id" : "<STRING>",
    "resource_type" : "<STRING>",
    "node_id" : "<STRING>",
    "cleared" : "<BOOLEAN>",
    "severity" : "<STRING of CLEARED, WARNING, MINOR, MAJOR, CRITICAL>",
    "dashboard_link" : "<URL>",
    "brief_description" : "<STRING>",
    "detailed_description": "<MULTILINE STRING>",
    "impacted_resources": "<MULTILINE STRING>",
    "suggested_actions": "<MULTILINE STRING>",
    "last_updated" : "<DATE AND TIME>"
}

Nested Format

The nested format has a structure where different parts of the alarm are represented in sub-maps. Multi-line text messages are represented using JSON arrays.

{
    "alarm_id" : "<STRING>",
    "identifier" : {
        "alarm_type" : "<STRING>",
        "resource_id" : "<STRING>",
        "resource_type": "<STRING>",
        "node_id": "<STRING>",
    },
    "cleared" : "<BOOLEAN>",
    "severity":  "<STRING of CLEARED, WARNING, MINOR, MAJOR, CRITICAL>",
    "description" : {
        "dashboard_link": "<URL>",
        "brief_description": "<STRING>",
        "detailed_description": ["<STRING>"],
        "suggested_actions": ["<STRING>"],
        "impact_descriptions": {
            "<TYPE>" : {
                "title" : "<STRING>",
                "impacted_dependencies" : ["<STRING>"]
            }
        }
    },
    "last_updated" : "<DATE AND TIME>"
}

Configuration

To configure the Webhook alarm handler, an HTTP client needs to be configured, along with the path, host and port to connect to. Any authentication mechanism is configured on the HTTP client, which supports Mutual TLS, Basic Authentication and OAuth Client Credentials.

The webhook is configured under /environments/environment/alarms/alarm-handlers/alarm-handler

Parameter Description
webhook-notifier/message-format Message format of either flat or nested
webhook-notifier/web-service/hostname Hostname of the service
webhook-notifier/web-service/port Port of the web service
webhook-notifier/web-service/context The path on the web service to post to
webhook-notifier/web-service/http-client The configured HTTP client to use (under facilities)
Listing 12 A configured webhook shown in the CLI
% show environments environment alarms alarm-handlers alarm-handler wh1
webhook-notifier {
    web-service {
        hostname    example.com;
        port        443;
        context     /postme;
        http-client trustStoreHttpClient;
    }
    message-format nested;
}