CheckMK Integration

Plugin URL: https://exchange.checkmk.com/p/alertops

The plugin follows the same architecture used by Checkmk's built-in notification plugins (PagerDuty, iLert, Opsgenie, Slack), including full GUI configuration through Checkmk's Setup interface.

Requirements

Requirement	Details
Checkmk Version	2.4.0p16 or later
Checkmk Edition	Raw (CRE), Enterprise (CEE), Cloud (CCE), or Managed (CME)
Python	3.x (bundled with Checkmk)
Network	HTTPS access to `notify.alertops.com` from the Checkmk server
AlertOps	An AlertOps account with an inbound integration configured

Plugin Architecture

The plugin consists of two files:

local/├── lib/python3/cmk/gui/plugins/wato/
│   └── alertops_notification_parameters.py   # GUI parameter form (WATO)
└── share/check_mk/notifications/
    └── alertops                               # Notification script

Notification Script (`alertops`)

The entry point that Checkmk executes when a notification rule fires. It:

Collects the notification context (host, service, state, output, etc.) from NOTIFY_* environment variables using Checkmk's built-in collect_context() utility.
Reads the webhook URL from the GUI-configured parameter (NOTIFY_PARAMETER_ALERTOPS_WEBHOOK_URL).
Builds a JSON payload with event key, severity mapping, timestamps, and alert metadata.
POSTs the payload to the AlertOps webhook using Checkmk's built-in post_request() utility, which handles proxy configuration, SSL settings, and timeouts.
Returns an appropriate exit code (0 = success, 1 = retry, 2 = permanent failure) based on the HTTP response.

GUI Parameter Registration (`alertops_notification_parameters.py`)

A WATO plugin that registers the AlertOps configuration form in Checkmk's notification rule editor. It subclasses NotificationParameter (the same base class used by PagerDuty, iLert, etc.) and defines the following configurable fields:

Field	Type	Required	Description
AlertOps Webhook URL	String (URL-validated)	Yes	The AlertOps inbound integration endpoint
Disable SSL verification	Checkbox	No	Skip TLS certificate validation
HTTP Proxy	Proxy selector	No	Route requests through an HTTP proxy

The ident property is set to "alertops", which must match the filename of the notification script in local/share/check_mk/notifications/.

Installation

Method 1: Manual File Deployment

Copy the plugin files into your Checkmk site's local directory structure:

SITE=mysite  # Replace with your site name

# Create directories
mkdir -p /omd/sites/$SITE/local/share/check_mk/notifications
mkdir -p /omd/sites/$SITE/local/lib/python3/cmk/gui/plugins/wato

# Copy files
cp alertops /omd/sites/$SITE/local/share/check_mk/notifications/alertops
cp alertops_notification_parameters.py /omd/sites/$SITE/local/lib/python3/cmk/gui/plugins/wato/

# Set ownership and permissions
chown $SITE:$SITE /omd/sites/$SITE/local/share/check_mk/notifications/alertops
chown $SITE:$SITE /omd/sites/$SITE/local/lib/python3/cmk/gui/plugins/wato/alertops_notification_parameters.py
chmod +x /omd/sites/$SITE/local/share/check_mk/notifications/alertops

# Restart the site to load the GUI plugin
omd restart $SITE

Method 2: MKP Package (Checkmk Extension Package)

Package the files as an MKP for distribution:

su - $SITE
mkp create alertops
# Follow the prompts to include the two plugin files

Method 3: Docker-Based Setup

Use the included setup.sh script:

./setup.sh

This pulls the Checkmk Docker image, starts a container, and deploys the plugin automatically.

Configuration

Step 1: Obtain Your AlertOps Webhook URL

Log in to your AlertOps account.
Navigate to Integrations → Inbound Integrations.
Create a new inbound integration or select an existing one.
Copy the webhook URL (format: https://notify.alertops.com/POSTAlert/<key>/CheckMK).

Step 2: Create a Notification Parameter Set

In Checkmk, go to Setup → Events → Notification configuration → Notification parameters.
Under AlertOps parameters, click Add parameter set.
Enter a description (e.g., "AlertOps Production").
Paste your AlertOps Webhook URL.
Optionally configure SSL and proxy settings.
Save.

Step 3: Create a Notification Rule

Go to Setup → Events → Notification configuration → Notification rules.
Click Add rule.
Under Notification method, select AlertOps.
Select the parameter set you created in Step 2.
Configure matching conditions:
- Host events: Select which state changes to notify on (e.g., DOWN, RECOVERY).
- Service events: Select which state changes to notify on (e.g., CRITICAL, WARNING, RECOVERY).
- Optionally filter by host groups, service groups, folders, or labels.
Under Contact selection, choose how to determine recipients (e.g., "All contacts of the notified object" or specific users).
Save and Activate changes.

Multiple Teams / Environments

To route alerts to different AlertOps teams or environments:

Create a separate notification parameter set for each AlertOps webhook URL.
Create a separate notification rule for each, with different host/service matching criteria.

For example:

Rule 1: Infrastructure hosts → AlertOps Infrastructure team webhook
Rule 2: Application services → AlertOps Application team webhook
Rule 3: Database hosts → AlertOps DBA team webhook

Each rule is configured entirely in the GUI. No server-side environment variables, no per-host configuration, no SSH access required.

JSON Payload Reference

The plugin sends the following JSON structure to the AlertOps webhook:

{
  "EventKey": "hostname_ServiceDesc",
  "Source": "Checkmk",
  "Host": "hostname",
  "HostAddress": "192.168.1.100",
  "Service": "CPU Load",
  "State": "CRITICAL",
  "Severity": "critical",
  "NotificationType": "PROBLEM",
  "Summary": "CRITICAL: CPU Load on hostname",
  "Message": "CRITICAL - 15min load 8.52 at 8 CPUs",
  "Resolved": false,
  "Timestamp": "2026-04-07T16:59:32Z",
  "DetailsURL": "https://checkmk.example.com/cmk/check_mk/view.py?...",
  "LongMessage": "Extended output from the check plugin (if available)"
}

Field Descriptions

Field	Type	Description
`EventKey`	string	Deduplication key. Format: `hostname` for host alerts, `hostname_ServiceDesc` for service alerts. Spaces replaced with underscores.
`Source`	string	Always `"Checkmk"`.
`Host`	string	The hostname as configured in Checkmk.
`HostAddress`	string	The IP address of the host.
`Service`	string	The service description (empty string for host alerts).
`State`	string	The Checkmk state: `OK`, `WARNING`, `CRITICAL`, `UNKNOWN` (services) or `UP`, `DOWN`, `UNREACHABLE` (hosts).
`Severity`	string	Normalized severity: `ok`, `warning`, `critical`, `unknown`.
`NotificationType`	string	`PROBLEM`, `RECOVERY`, `ACKNOWLEDGEMENT`, `CUSTOM`, `DOWNTIME_START`, `DOWNTIME_END`, `DOWNTIME_CANCELLED`.
`Summary`	string	One-line human-readable alert summary.
`Message`	string	The check plugin output text.
`Resolved`	boolean	`true` if the alert is a recovery or the state is OK/UP.
`Timestamp`	string	ISO 8601 UTC timestamp of when the notification was generated.
`DetailsURL`	string	(Optional) Direct link to the host/service in the Checkmk GUI. Only present if URL prefix is configured.
`LongMessage`	string	(Optional) Extended/multi-line check output, if available.

Testing

Method 1: Direct Script Invocation

The fastest way to validate end-to-end delivery. Set the required environment variables and run the script directly:

su - $SITE

export NOTIFY_WHAT=HOST
export NOTIFY_HOSTNAME=test-host
export NOTIFY_HOSTADDRESS=192.168.1.100
export NOTIFY_HOSTSTATE=DOWN
export NOTIFY_HOSTOUTPUT="PING CRITICAL - Host unreachable"
export NOTIFY_NOTIFICATIONTYPE=PROBLEM
export NOTIFY_PARAMETER_ALERTOPS_WEBHOOK_URL="https://notify.alertops.com/POSTAlert/<your-key>/CheckMK"

python3 ~/local/share/check_mk/notifications/alertops

Expected output on success: 200: OK

For a service alert:

export NOTIFY_WHAT=SERVICE
export NOTIFY_HOSTNAME=test-host
export NOTIFY_HOSTADDRESS=192.168.1.100
export NOTIFY_HOSTSTATE=UP
export NOTIFY_SERVICEDESC="CPU Load"
export NOTIFY_SERVICESTATE=CRITICAL
export NOTIFY_SERVICEOUTPUT="CRITICAL - 15min load 8.52 at 8 CPUs"
export NOTIFY_NOTIFICATIONTYPE=PROBLEM
export NOTIFY_PARAMETER_ALERTOPS_WEBHOOK_URL="https://notify.alertops.com/POSTAlert/<your-key>/CheckMK"

python3 ~/local/share/check_mk/notifications/alertops

Method 2: Checkmk Notification Simulation

Use Checkmk's built-in simulation to verify rule matching (note: simulation does not execute the script — it only confirms which rules would match):

Go to Setup → Events → Notification configuration.
Click Test notifications.
Select a host and optionally a service.
Click Test.
Verify the AlertOps rule appears in the results with status "would notify".

Method 3: Trigger a Real State Change

Create a test host or use a local check that you can toggle between states:

# Create a local check on the Checkmk server
cat > /omd/sites/$SITE/local/share/check_mk/agents/local/alertops_test <<'EOF'
#!/bin/bash
STATE_FILE="/tmp/alertops_test_state"
[ -f "$STATE_FILE" ] && STATE=$(cat "$STATE_FILE") || STATE=0
echo "${STATE} AlertOps_Test_Service - Test service for AlertOps notifications"
EOF
chmod +x /omd/sites/$SITE/local/share/check_mk/agents/local/alertops_test

Then toggle the state:

echo 2 > /tmp/alertops_test_state   # CRITICAL — triggers PROBLEM notification
echo 0 > /tmp/alertops_test_state   # OK — triggers RECOVERY notification

Checking Notification Logs

# View the notification log
tail -f /omd/sites/$SITE/var/log/notify.log

# Filter for AlertOps entries
grep alertops /omd/sites/$SITE/var/log/notify.log

Troubleshooting

"No AlertOps webhook URL configured"

The webhook URL parameter is not reaching the script. Verify:

The notification rule references a parameter set that contains the webhook URL.
The parameter set has a value in the "AlertOps Webhook URL" field.
Changes have been activated after saving the rule.

"would notify" in logs but no alert in AlertOps

This means you used the notification simulation feature. Simulation only tests rule matching — it does not execute notification scripts. Use Method 1 (direct invocation) or Method 3 (real state change) to test actual delivery.

HTTP 401 / 403 from AlertOps

The webhook URL is invalid or the integration has been disabled in AlertOps. Verify the URL in your AlertOps Inbound Integration settings.

HTTP 5xx from AlertOps

AlertOps is experiencing a server-side issue. The script returns exit code 1 for 5xx errors, which tells Checkmk to retry the notification later.

Connection timeout

The Checkmk server cannot reach notify.alertops.com. Check:

DNS resolution: nslookup notify.alertops.com
Firewall rules: outbound HTTPS (443) must be allowed.
Proxy configuration: if you use a proxy, configure it in the notification parameters.

SSL certificate errors

If you are behind a TLS-inspecting proxy or firewall, enable the "Disable SSL certificate verification" option in the notification parameters.

Exit Codes

The plugin follows Checkmk's notification plugin exit code convention:

Exit Code	Meaning	Checkmk Behavior
0	Success	Notification marked as delivered
1	Temporary failure (5xx)	Checkmk will retry the notification
2	Permanent failure	Notification marked as failed, no retry

Security Considerations

The webhook URL is stored in Checkmk's notification parameter configuration and is not exposed in the GUI after saving.
All communication with AlertOps uses HTTPS by default.
Proxy credentials (if configured) are handled through Checkmk's built-in proxy configuration system.
The plugin does not write any alert data to local disk or log files beyond Checkmk's standard notification log.

Compatibility

Checkmk Raw Edition (CRE): Fully supported.
Checkmk Enterprise Edition (CEE): Fully supported.
Docker deployments: Fully supported (the plugin runs inside the container, no host-level dependencies).
Distributed monitoring: Each site must have the plugin installed locally. The webhook URL is configured per notification rule, which can be distributed across sites.
Python 3.12+: Compatible (uses only standard library + Checkmk's bundled requests library via cmk.notification_plugins.utils).