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 2 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;
}