Checkmk Webhook Setup Guide

The Native Webhook URL is generated once an account has been linked. You pass it to the script as its only parameter in a later step.

• Open the linked account in StackOne.
• Copy the value from Native Webhook URL.
• The URL contains a secret token that authenticates deliveries, so store it securely and do not share it.

Save the script below on the Checkmk server as /omd/sites/<site-id>/local/share/check_mk/notifications/stackone_webhook, where <site-id> is your Checkmk site name (for example mysite). Run the commands as the site user, for example after omd su <site-id>. The script uses only the Python 3 standard library that ships with Checkmk and needs no extra packages.

#!/usr/bin/env python3
# StackOne Webhook
# Forwards Checkmk notifications to StackOne as JSON.
# Parameter 1 (required) = StackOne Native Webhook URL
import json, os, sys, urllib.error, urllib.request
from datetime import datetime, timezone

TYPES = {
    "ACKNOWLEDGEMENT": "acknowledged",
    "FLAPPINGSTART": "flapping_started",
    "FLAPPINGSTOP": "flapping_stopped",
    "DOWNTIMESTART": "downtime_started",
    "DOWNTIMEEND": "downtime_ended",
    "DOWNTIMECANCELLED": "downtime_cancelled",
}
HOST_PROBLEMS = {"DOWN": "host_down", "UNREACHABLE": "host_unreachable"}
SERVICE_PROBLEMS = {"WARN": "service_warning", "WARNING": "service_warning",
                    "CRIT": "service_critical", "CRITICAL": "service_critical",
                    "UNKNOWN": "service_unknown"}


def classify(ntype, what, hs, ss):
    scope = "service" if what == "SERVICE" else "host"
    if ntype == "CUSTOM":
        return "verification"
    if ntype == "PROBLEM":
        problems = SERVICE_PROBLEMS if scope == "service" else HOST_PROBLEMS
        return problems.get(ss if scope == "service" else hs, "unmapped")
    if ntype == "RECOVERY":
        return "service_ok" if scope == "service" else "host_up"
    if ntype in TYPES:
        return "%s_%s" % (scope, TYPES[ntype])
    return "unmapped"


def main():
    e = {k[7:]: v for k, v in os.environ.items() if k.startswith("NOTIFY_")}
    url = e.get("PARAMETER_1")
    if not url:
        sys.stderr.write("stackone_webhook: missing webhook URL parameter\n")
        return 2
    ntype, what = e.get("NOTIFICATIONTYPE", ""), e.get("WHAT", "")
    hs, ss = e.get("HOSTSTATE", ""), e.get("SERVICESTATE", "")
    event = classify(ntype, what, hs, ss)
    micro = e.get("MICROTIME")
    if micro:
        ts = datetime.fromtimestamp(int(micro) / 1e6, tz=timezone.utc).isoformat()
    else:
        ts = datetime.now(timezone.utc).isoformat()
    service = e.get("SERVICEDESC") if what == "SERVICE" else None
    subject = e.get("HOSTNAME", "unknown") + (":" + service if service else "")
    body = {
        "event": event,
        "event_id": "%s-%s-%s" % (subject, ntype, micro or ts),
        "event_date": ts,
        "notification_type": ntype,
        "what": what,
        "host_name": e.get("HOSTNAME"),
        "host_address": e.get("HOSTADDRESS"),
        "host_state": hs or None,
        "previous_host_state": e.get("LASTHOSTSTATE") or None,
        "host_output": e.get("HOSTOUTPUT"),
        "service_description": service,
        "service_state": (ss or None) if service else None,
        "previous_service_state": (e.get("LASTSERVICESTATE") or None) if service else None,
        "service_output": e.get("SERVICEOUTPUT") if service else None,
        "contact_name": e.get("CONTACTNAME"),
        "omd_site": e.get("OMD_SITE"),
        "long_date_time": e.get("LONGDATETIME"),
    }
    req = urllib.request.Request(url, data=json.dumps(body).encode(),
                                 headers={"Content-Type": "application/json",
                                          "User-Agent": "stackone-checkmk-webhook/2.0",
                                          "Accept": "application/json"})
    try:
        urllib.request.urlopen(req, timeout=10)
    except urllib.error.HTTPError as err:
        if event == "unmapped" and err.code == 400:
            return 0  # StackOne deliberately does not route unmapped notification types
        raise
    return 0


if __name__ == "__main__":
    sys.exit(main())

• Make the script executable with chmod +x /omd/sites/<site-id>/local/share/check_mk/notifications/stackone_webhook.
• The script appears as StackOne Webhook in the notification method list.

In the Checkmk navigation bar, open Setup and click Notifications in the Events section.

On the Notifications page, click Add notification rule.

In Triggering events, select All events so every host and service notification is forwarded, or keep Specific events and pick only the host and service state changes you need. Click Next step: Specify host/services, optionally narrow the rule in Filter for hosts/services, then continue to Notification method (plug-in).

• Checkmk’s factory Notified events for hosts rule excludes the unreachable state, so Host Unreachable (host_unreachable) events never fire out of the box. To receive them, edit that rule under Supporting rules on the Notifications page and include unreachable events.

In Notification method (plug-in), keep Send notification, open the method dropdown and select StackOne Webhook.

Next to Select parameters, click Create to add a parameter set for the method.

In New StackOne Webhook parameter, enter a Description such as StackOne webhook. Under Parameters, paste the Native Webhook URL from the linked account into the first field of Call with the following parameters, then click Save. The new parameter set is selected automatically.

• Parameter sets can be edited later from the Notifications page via Parameters for notification methods.

In Recipient, change Select recipient to Specific users and pick one user who can see all hosts and services. Checkmk runs the script once per recipient, so a single user sends each event to StackOne exactly once. The recipient does not change where events are delivered.

Skip Sending conditions. In General properties, enter a Description such as StackOne webhook and click Next step: Review all settings.

Review the summary and click Apply & test notification rule. Checkmk saves the rule and opens Test notifications.

On Test notifications, choose a Host, tick Trigger notification for a specific method, select StackOne Webhook and your parameter set under Notification method and parameter, then click Test notifications.

• Without Trigger notification for a specific method, Checkmk only analyzes which rules would match and sends nothing.
• The test simulates a real state change (by default UP to DOWN), so StackOne receives it as a Host Down (host_down) event.

Open a monitored host in Monitor, open the Commands menu and choose Send custom notification (click the show-more icon in the menu if it is not listed).

Enter a Comment and click Send, then confirm with Send. StackOne receives the notification as a Webhook Verification (verification) event.

Fired by a Checkmk custom notification rather than a real state change.

• Webhook Verification (verification) — Fired when an admin sends a Checkmk custom notification; used to confirm the webhook is wired correctly

Events related to the state of monitored hosts.

• Host Down (host_down) — Fired when a monitored host changes to the DOWN state
• Host Unreachable (host_unreachable) — Fired when a host becomes UNREACHABLE, typically because its parent host is down
• Host Up (host_up) — Fired when a monitored host recovers to the UP state
• Host Problem Acknowledged (host_acknowledged) — Fired when a contact acknowledges a host problem
• Host Flapping Started (host_flapping_started) — Fired when a host starts flapping between states
• Host Flapping Stopped (host_flapping_stopped) — Fired when a host stops flapping between states
• Host Downtime Started (host_downtime_started) — Fired when a scheduled downtime begins for a host
• Host Downtime Ended (host_downtime_ended) — Fired when a scheduled host downtime ends at its planned end time
• Host Downtime Canceled (host_downtime_cancelled) — Fired when a scheduled host downtime is removed before its planned end time

Events related to the state of monitored services.

• Service Warning (service_warning) — Fired when a service enters the WARNING state
• Service Critical (service_critical) — Fired when a service enters the CRITICAL state
• Service Unknown (service_unknown) — Fired when a service enters the UNKNOWN state
• Service Recovered (service_ok) — Fired when a service recovers to the OK state
• Service Problem Acknowledged (service_acknowledged) — Fired when a contact acknowledges a service problem
• Service Flapping Started (service_flapping_started) — Fired when a service starts flapping between states
• Service Flapping Stopped (service_flapping_stopped) — Fired when a service stops flapping between states
• Service Downtime Started (service_downtime_started) — Fired when a scheduled downtime begins for a service
• Service Downtime Ended (service_downtime_ended) — Fired when a scheduled service downtime ends at its planned end time
• Service Downtime Canceled (service_downtime_cancelled) — Fired when a scheduled service downtime is removed before its planned end time

Each Checkmk notification produces a single HTTPS POST with a flat JSON body; there is no batching. The event field identifies the event, event_id and event_date are generated by the script, and host or service fields that do not apply to an event are null. Notification types without a matching event (such as alert handler notifications) are sent with event set to unmapped and are not processed by StackOne. Requests are not signed; delivery security relies on the secret embedded in the Native Webhook URL.