Webhook Notifier

Usage#

When built-in alarm handlers do not meet specific integration requirements, the Webhook Notifier can be used to send alarm notifications to custom endpoints, using HTTP requests with a JSON body in the configured message format .

Getting Started#

To create a new Webhook Notifier, navigate to System → Alarm Handlers and click the New Alarm Handler button. Give a name to the handler and, select the Webhook handler type.

Finally, provide the required configuration properties for the new handler and commit the configuration.

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 configuration-reference/environments/environment/alarms/alarm-handlers/alarm-handler

# A configured Webhook Notifier 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;
}

Message Format#

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:

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>"
}