Matrix Notifications for Checkmk – Modern, Secure, and Self-Hosted Alerting

Still sending monitoring alerts via email or relying on closed messaging platforms? In an age where digital sovereignty matters more than ever, it’s time to rethink how we handle critical system alerts.

For our infrastructure, we wanted a fast, secure, and self-hosted way to receive Checkmk notifications — without handing over data to third-party services. That’s why I built a lightweight integration that lets Checkmk send alerts directly to a Matrix room — using nothing but a shell script and open protocols.

Matrix notification examples

This article introduces the idea, explains how it works, and shows you how to use it in your own monitoring stack.

Why Matrix?

Matrix is a modern, decentralized messaging protocol. Compared to traditional methods like email or SMS, it offers:

✅ Real-time delivery

✅ End-to-end encryption

✅ Federated infrastructure

✅ Bots, bridges, and open APIs

It’s ideal for infrastructure admins who value openness, privacy, and control over their tools.

Why Not Email?

Email is still widely used, but far from ideal:

❌ Delayed delivery, especially in complex environments

❌ Spam filters, HTML rendering issues

❌ No instant push notification experience

❌ Difficult to automate or respond to

Matrix, on the other hand, delivers alerts instantly to mobile and desktop clients — and integrates easily with automation or bot workflows.

The Solution: A Simple Shell Script

This integration consists of a small shell script that uses the Matrix Client-Server API. It is designed to work seamlessly with Checkmk notification rules.

Key Features:

  • Sends messages via a simple PUT request
  • Uses a unique transaction ID to avoid duplicate messages
  • No extra software required — just curl and a valid Matrix token
  • You can see the result directly in your Matrix app — mobile or desktop.

How It Works

Checkmk exports environment variables into the notification script. Among them:

NOTIFY_CONTACT_MATRIX_ROOM_ID
NOTIFY_CONTACT_MATRIX_API_TOKEN
NOTIFY_CONTACT_MATRIX_HOMESERVER

The script composes a JSON payload and sends it to Matrix using this pattern:

curl -X PUT "${HOMESERVER}/_matrix/client/v3/rooms/${ROOM_ID}/send/m.room.message/${TXN_ID}?access_token=${TOKEN}" \     
-H "Content-Type: application/json" \     
-d "{\"msgtype\":\"m.text\", \"body\":\"${MESSAGE}\"}"

Download & Source

👉 Get the latest version from GitHub: https://github.com/filipnet/checkmk-matrix-notify

Includes:

  • Full source code
  • Sample configuration
  • Troubleshooting guide

Conclusion

Matrix is a perfect match for modern monitoring: fast, secure, open, and under your control. This integration brings Checkmk into the 2020s by offering real-time alerts on all your devices — without relying on external providers.

If you care about digital independence, privacy, and flexibility: Try it out