Starting with version 1.6, Checkmk natively integrates with Opsgenie, letting you create, close, and acknowledge alerts without a custom plugin.

LAST TESTED ON CHECKMK 2.4.0P16

Table of Contents

Overview

This article explains how to configure Opsgenie notifications in Checkmk using the built-in Opsgenie integration. The integration allows Checkmk to create, close, and acknowledge Opsgenie alerts without requiring a custom plugin.

The instructions in this article were tested with the Opsgenie Essential subscription and Checkmk version 2.4.0p16. Other Opsgenie subscription tiers or Checkmk versions may require additional or different configuration steps. For further information, please read our Official Documentation on Notifications via Opsgenie.

Prerequisites

Before you begin, ensure that the following requirements are met:

An active Opsgenie account
One or more Opsgenie teams created, with team members assigned
A running Checkmk site with access to user and notification configuration
Network connectivity from Checkmk to the Opsgenie API endpoint

Step-by-step guide

Create Opsgenie teams

Log in to your Opsgenie account and create the required teams if they do not already exist. Teams are typically used to represent operational groups such as Linux, Database, or Site Reliability Engineering (SRE) teams.

Assign the appropriate users to each team. These users will act as responders for alerts generated by Checkmk.

Enable the Checkmk integration in Opsgenie

For each team or for the entire Opsgenie account, activate the Checkmk integration.

When enabling the integration:

Provide a meaningful integration name
Assign the integration to the correct team
Generate the API key

Make a note of each generated API key
These keys are required later when configuring notifications in Checkmk and should be stored securely.

Depending on your setup, you may use:

A single integration and API key for all teams
Separate integrations and API keys per team

Create technical users in Checkmk

In Checkmk, create a technical user for each Opsgenie integration. If each Opsgenie team uses a separate API key, create one technical user per team.

In Checkmk, click Setup.
Click Users.
Click Add user.
In Username, enter the technical username.
In Full name, enter a descriptive name (for example, "OpsGenie User").
Under Authentication, leave the default setting unchanged.
Enable Disable the login to this account.
Under Roles, leave Normal monitoring user enabled.
Click Save.

Why a technical notification user is required

Checkmk notification rules are always associated with a user object. For integrations such as Opsgenie, this user does not represent a real person and is used only to send notifications.

Disabling login ensures that the account cannot be used for interactive access while still allowing Checkmk to execute notifications securely. The Normal monitoring user role provides sufficient permissions for notification handling without granting administrative access.

Configure the custom notification table

For each technical user, open the user configuration and click the bell icon to access the custom notification table.

Add a new notification rule and select Opsgenie as the notification method.

In the Opsgenie notification configuration:

Enter the Opsgenie API key
Define the alert owner
Select the responsible team or teams

The responsible team value is passed to Opsgenie and appears as the responder for the alert.

Leave all other fields at their default values unless you have specific requirements.

Define matching conditions

Matching conditions are mandatory. They determine which hosts or services trigger the Opsgenie notification.

Examples of matching criteria include:

Matching a specific host or host group
Matching a specific service or service group
Matching host or service state transitions

When using multiple Opsgenie integrations, ensure that matching rules do not overlap. If two notification rules match the same event, only the first matching rule is applied.

Carefully design your conditions to avoid unintended alert routing.

Test notification rules

Use the "Test notifications" feature in Checkmk to validate your matching conditions.

During a test notification:

No alert is sent to Opsgenie
The result is logged in $OMD_ROOT/var/log/notify.log
A successful match is shown as "would notify"

This step verifies that the rule configuration is correct before generating real alerts.

Generate a test alert

To verify end-to-end alert creation in Opsgenie, trigger a real alert by generating a HARD STATE in Checkmk.

You can do this by:

Using the Fake check results action for a service.
Temporarily setting the Maximum number of check attempts for the service to 1

Once the service enters a HARD non-OK state, Checkmk sends the alert to Opsgenie using the configured notification rule.

Verify alerts in Opsgenie

Log in to Opsgenie and open the Alerts section.

Verify that:

A new alert is created
The alert source is Checkmk
The responsible team matches the configured responder
Host and service details are included in the alert description

If multiple responsible teams are configured, the alert is assigned to all listed responders.

Additional information

Tags

Tags may only contain letters, digits, dashes, and underscores, and must start with a letter or an underscore. Spaces are not permitted.

Example of valid tags:

team1
team-1
team_1
_team1

Debugging notifications

To troubleshoot notification issues:

Increase the debug level for Notifications in the Checkmk global settings
Review the output in ~/var/log/cmc.log and notify.log

API connectivity testing

To verify connectivity to the Opsgenie API from the Checkmk command line, run:

curl -X GET 'https://api.opsgenie.com/v2/teams' --header 'Authorization: GenieKey <your_api_key>' | json_pp

This helps identify firewall or proxy related issues.

API version note

At the time of testing, the Checkmk integration uses the Opsgenie v1 API endpoint. Future Checkmk releases are expected to migrate to the v2 API.

How-to configure Opsgenie notifications