Zurück zum Blog

Uptime Kuma Push-Benachrichtigungen aufs Handy: laut bei Ausfall, leise bei Wiederherstellung

Uptime Kuma Push-Benachrichtigungen aufs Handy: laut bei Ausfall, leise bei Wiederherstellung

Uptime Kuma erkennt zuverlässig, wenn etwas ausfällt. Wo diese Meldung dann landet, ist eine andere Frage. Die meisten Setups schicken sie in eine Telegram-Gruppe, einen Discord-Kanal oder einen E-Mail-Ordner, zwischen all den anderen Dingen, die dein Handy den Tag über zum Vibrieren bringen. Und die Meldung „wieder online“ macht genau denselben Lärm wie „ausgefallen“. Nach ein paar Nächten mit flackernden Checks stellen Leute den Kanal stumm und lesen ihn nicht mehr.

Diese Anleitung schickt Uptime-Kuma-Meldungen als Push-Benachrichtigungen mit unterschiedlichen Prioritäten an Pocket Alert. Fällt ein Monitor aus, kommt die Meldung als high an, und die durchdringt den Fokus auf dem iPhone. Eine Wiederherstellung kommt als low an: Sie steht im Feed, wenn du draufschaust, und weckt niemanden. Alles läuft über den eingebauten Benachrichtigungstyp Webhook von Uptime Kuma, daneben musst du nichts installieren.

Alles unten wurde mit Uptime Kuma 2.5.8 in Docker getestet.

Was du brauchst

  • Uptime Kuma 2.x. Das meiste funktioniert auch mit 1.23.x; die Unterschiede stehen am Ende.
  • Die Pocket-Alert-App auf deinem Handy und ein Konto. Registriere dich, falls du noch keins hast; der kostenlose Tarif reicht zum Einstieg.
  • Einen API-Schlüssel aus API-Schlüssel (Weg 1) oder einen Webhook aus Webhooks (Weg 2).

Zwei Wege zur Verbindung

Die Webhook-Benachrichtigung von Uptime Kuma kann an jede beliebige URL senden, entweder mit ihrem eigenen JSON oder mit einem Body, den du selbst schreibst. Daraus ergeben sich zwei Wege:

Weg 1: Pocket-Alert-APIWeg 2: Pocket-Alert-Webhook-URL
Ziel-URL (POST)https://api.pocketalert.app/v1/messageshttps://p4a.me/wh/<slug>
Push-TitelFrei wählbar, z. B. Down: WebsiteImmer Webhook <name>
Down laut, Up leiseJaJa, mit eigenem Body; sonst eine Stufe für alles
Geheimnis in Uptime KumaEin API-Schlüssel mit vollem Zugriff auf dein KontoEine URL, mit der sich nur Pushes über diesen Webhook erstellen lassen
Anfragenprotokoll in Pocket AlertNeinJa, im Webhook-Verlauf

Nimm Weg 1, wenn du lesbare Titel willst und möglichst wenige bewegliche Teile. Nimm Weg 2, wenn du keinen vollständigen API-Schlüssel in Uptime Kuma speichern willst (dort liegen die Benachrichtigungseinstellungen, Header inklusive, als Klartext-JSON in der Datenbank), oder wenn du jede Anfrage, die Uptime Kuma sendet, zum Debuggen auf der Pocket-Alert-Seite protokolliert haben möchtest.

Weg 1: direkt an die Pocket-Alert-API senden

Öffne in Uptime Kuma Einstellungen → Benachrichtigungen und klicke auf Set Up Notification. Fülle es so aus:

  • Notification Type: Webhook
  • Friendly Name: Pocket Alert
  • Post URL: https://api.pocketalert.app/v1/messages
  • HTTP Method: POST
  • Request Body: Custom Body

Füge Folgendes in das Body-Feld ein und ersetze kuma.example.com durch die Adresse deines Uptime Kuma:

{%- assign level = "default" -%}
{%- assign title = "Uptime Kuma" -%}
{%- assign text = msg -%}
{%- if heartbeatJSON -%}
  {%- assign text = heartbeatJSON.msg | default: msg -%}
  {%- if heartbeatJSON.status == 0 -%}
    {%- assign title = "Down: " | append: monitorJSON.name -%}
    {%- assign level = "high" -%}
    {%- for tag in monitorJSON.tags -%}
      {%- if tag.name == "critical" -%}{%- assign level = "critical" -%}{%- endif -%}
    {%- endfor -%}
  {%- else -%}
    {%- assign title = "Up: " | append: monitorJSON.name -%}
    {%- assign level = "low" -%}
  {%- endif -%}
{%- elsif msg contains "will expire" -%}
  {%- assign title = "Expiring soon" -%}
{%- endif -%}
{
  "title": {{ title | json }},
  "message": {{ text | json }},
  "level": "{{ level }}",
  "actions": [
    {
      "type": "view",
      "label": "Open in Uptime Kuma",
      "value": "https://kuma.example.com/dashboard/{{ monitorJSON.id }}"
    }
  ]
}

Aktiviere danach Additional Headers und füge ein:

{
  "Token": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Was der Body macht:

  • Der Body ist ein Liquid-Template. Uptime Kuma übergibt msg (seinen fertigen Text), monitorJSON (den Monitor) und heartbeatJSON (den Check, der den Status geändert hat). heartbeatJSON.status ist 0 für down und 1 für up.
  • | json schreibt einen vollständigen JSON-String inklusive Anführungszeichen. Fehlermeldungen und Monitornamen können Anführungszeichen und Backslashes enthalten; mit dem Filter können sie die Anfrage nicht kaputt machen. Ein Monitor namens Bob's "main" site ergibt trotzdem gültiges JSON.
  • Down ist high, Up ist low. high ist auf dem iPhone zeitkritisch und kommt am Fokus und an der geplanten Zusammenfassung vorbei. low wird zugestellt, ohne dich zu unterbrechen.
  • Markiere einen Monitor mit critical, damit er lauter wird. Füge in Uptime Kuma den Tag critical zu den wichtigsten Monitoren hinzu. Ihre Ausfälle werden dann als critical gesendet und spielen auch bei stummgeschaltetem Schalter und bei „Nicht stören“ ab. Kritische Benachrichtigungen sind ein kostenpflichtiges Feature; im kostenlosen Tarif werden sie als high zugestellt.
  • Zertifikats- und Testmeldungen haben keinen Heartbeat. Für diese nutzt der Push Uptime Kumas eigenen Text als Nachricht. Derselbe Text dient als Ersatz, wenn die Heartbeat-Meldung leer ist, etwa bei einem Ping-Monitor, der wieder online geht; die API lehnt einen Push mit leerer Nachricht ab.
  • Der Button öffnet den Monitor. /dashboard/<id> ist die Seite des Monitors in Uptime Kuma. Bei einer Zertifikatswarnung gibt es keine Monitor-ID, dann öffnet der Button stattdessen das Dashboard. Aktionsbuttons sind ein kostenpflichtiges Feature; im kostenlosen Tarif entfernt die API sie, und der Push kommt ohne Button an. Was Aktionsbuttons sonst noch können, steht unter Aktionsbuttons.

Lass den Content-Type-Header nicht weg. Wenn Uptime Kuma einen eigenen Body sendet, kennzeichnet es ihn als application/x-www-form-urlencoded, sofern du nichts anderes angibst. Das hat es in meinem Test so gesendet. Die Pocket-Alert-API akzeptiert nur JSON oder Multipart und antwortet auf diese Anfrage mit 400.

Klicke auf Test. Innerhalb weniger Sekunden sollte ein Push mit dem Titel „Uptime Kuma“ und dem Text „Pocket Alert Testing“ ankommen. Speichere dann.

So sahen ein echter Ausfall und eine Wiederherstellung aus, gesendet von Uptime Kuma 2.5.8:

{
  "title": "Down: Website",
  "message": "timeout of 4000ms exceeded",
  "level": "high",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
{
  "title": "Up: Website",
  "message": "200 - OK",
  "level": "low",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}

Verwende einen eigenen API-Schlüssel, benannt nach Uptime Kuma, damit du ihn einzeln widerrufen kannst, falls dieser Server jemals kompromittiert wird.

Weg 2: eine Pocket-Alert-Webhook-URL

Hier sendet Uptime Kuma sein eigenes JSON an einen Pocket-Alert-Webhook, und ein Template auf der Pocket-Alert-Seite macht daraus eine Push-Benachrichtigung.

Webhook anlegen

Die Button-Vorlage lässt sich nur über die API setzen, der schnellste Weg ist also ein einziger Aufruf. Er legt einen Webhook namens „Uptime Kuma“ mit einer Nachrichtenvorlage, der Standardstufe high (1) und einem Button „Open in Uptime Kuma“ an und gibt dann die Empfangs-URL aus:

PA_KEY='your-api-key'
KUMA_URL='https://kuma.example.com'

jq -n --arg kuma "$KUMA_URL" '{
  name: "Uptime Kuma",
  message: "%msg%",
  default_level: 1,
  actions: ([{type: "view", label: "Open in Uptime Kuma", value: ($kuma + "/dashboard/%monitor.id%")}] | tojson)
}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'

Wenn du lieber klickst, lege ihn in der Konsole unter Webhooks an: Name Uptime Kuma, Default priority High, Nachricht %msg%. Du bekommst dieselben Pushes, nur ohne Button.

Uptime Kuma darauf ausrichten

Lege eine neue Benachrichtigung vom Typ Webhook an, füge die Empfangs-URL als Post URL ein und stelle Request Body auf Preset - application/json. Header sind nicht nötig: Die URL ist das Geheimnis, also behandle sie wie ein Passwort. Wähle nicht das Multipart-Preset; Pocket-Alert-Webhooks lesen nur JSON.

Uptime Kuma hat mir bei meinem Testaufbau beim Ausfall eines Monitors Folgendes gesendet (gekürzt; das Objekt monitor hat rund hundert Felder):

{
  "heartbeat": {
    "monitorID": 1,
    "status": 0,
    "time": "2026-10-31 16:09:56.331",
    "msg": "timeout of 4000ms exceeded",
    "important": true,
    "localDateTime": "2026-10-31 16:09:56"
  },
  "monitor": {
    "id": 1,
    "name": "Website",
    "url": "http://tls-target/",
    "type": "http",
    "tags": []
  },
  "msg": "[Website] [🔴 Down] timeout of 4000ms exceeded"
}

Die Vorlage %msg% verwendet das oberste Feld msg, weil es das einzige Feld ist, das in jeder Anfrage vorhanden ist. Bei Zertifikatswarnungen und Testmeldungen sind heartbeat und monitor null, und nur msg ist gefüllt. Der Push kommt mit dem Titel „Webhook Uptime Kuma“ und dem Text „[Website] [🔴 Down] timeout of 4000ms exceeded“ an. Ein Platzhalter, dessen Pfad fehlt, wird zu einem leeren String, bei einer Zertifikatswarnung zeigt der Button also auf /dashboard/ und funktioniert trotzdem.

Down laut, Up leise auf diesem Weg

Mit dem JSON-Preset bekommt jede Anfrage die Standardstufe des Webhooks, Wiederherstellungen kommen also genauso laut an wie Ausfälle. Um das zu ändern, stelle Request Body auf Custom Body und sende selbst ein Feld level. Pocket-Alert-Webhooks lesen zuerst ein oberstes level aus der Payload und greifen erst danach auf die Standardstufe zurück:

{
  "level": "{% if heartbeatJSON %}{% if heartbeatJSON.status == 0 %}high{% else %}low{% endif %}{% else %}default{% endif %}",
  "msg": {{ msg | json }},
  "monitor": { "id": "{{ monitorJSON.id }}" }
}

Der Body behält die Feldnamen msg und monitor.id, daher funktionieren die Nachrichten- und Button-Vorlagen des Webhooks unverändert. Pocket-Alert-Webhooks lesen den Body unabhängig vom Content-Type als JSON, dieser Weg braucht also keinen zusätzlichen Header.

Für jeden Monitor aktivieren

Eine Benachrichtigung tut nichts, solange kein Monitor sie verwendet. Unten im Formular für Benachrichtigungen gibt es zwei Schalter:

  • Default enabled aktiviert diese Benachrichtigung für jeden Monitor, den du ab jetzt anlegst.
  • Apply on all existing monitors fügt sie allen bereits vorhandenen Monitoren hinzu. Das passiert einmal beim Speichern und wird nicht gespeichert.

Aktiviere beide beim ersten Speichern. Um einen Monitor davon auszuschließen, öffne ihn und entferne das Häkchen bei der Benachrichtigung in seinem Bearbeitungsformular.

Warnungen vor Zertifikatsablauf

Uptime Kuma kann dich warnen, bevor ein TLS-Zertifikat abläuft. Öffne einen HTTP(s)-Monitor (Keyword- und JSON-Query-Monitore haben das auch) und setze unter Advanced das Häkchen bei Certificate Expiry Notification. Das Feld ist ausgegraut, solange Ignore TLS/SSL errors for HTTPS websites aktiv ist.

Die Schwellenwerte sind global, unter Einstellungen → Benachrichtigungen → TLS Certificate Expiry, und stehen standardmäßig auf 7, 14 und 21 Tage. Die Warnung geht an dieselben Benachrichtigungen wie die Ausfälle des Monitors, mit einem Text wie:

[TLS site][https://tls-target/] server certificate tls-target will expire in 4 days

Der Body für Weg 1 erkennt sie mit msg contains "will expire" und setzt den Titel auf „Expiring soon“ mit der Stufe default. Uptime Kuma sendet sie einmal pro Schwellenwert, nicht bei jedem Check: In meinem Test wurde der Monitor 119-mal geprüft, bei einem Zertifikat, das noch vier Tage gültig war, und genau eine Warnung ging raus.

Verhindere, dass ein flackernder Monitor dein Handy flutet

Drei Monitor-Einstellungen bestimmen, wie viel Lärm ein instabiler Dienst macht:

EinstellungWas sie bewirktEmpfehlung
RetriesFehlgeschlagene Checks, die als Pending markiert werden, bevor der Monitor als down zählt. Pending-Checks benachrichtigen nicht.2 oder 3
Heartbeat Retry IntervalSekunden zwischen den Checks, solange der Status Pending ist.20 bis 60
Resend Notification if Down X times consecutivelyWiederholt die Down-Meldung nach so vielen weiteren fehlgeschlagenen Checks. 0 sendet sie nur einmal.0 oder ein Wert, der 30 bis 60 Minuten ergibt

Mit Retries auf 2 in meinem Test wurden die ersten zwei fehlgeschlagenen Checks als Pending markiert, und erst der dritte hat „Down“ gesendet. Mit Resend auf 3 wiederholte sich die Down-Meldung nach jeweils drei weiteren fehlgeschlagenen Checks, bis der Dienst wieder lief. Die Resend-Anzahl zählt Checks, keine Minuten. Bei einem Intervall von 60 Sekunden bedeutet 30 eine Erinnerung alle halbe Stunde.

Jeder Down-Fall, jede Wiederherstellung und jede Wiederholung ist eine Nachricht. Der kostenlose Tarif erlaubt 50 pro Tag, ein flackernder Monitor ohne Wiederholungen kann das an einem Nachmittag aufbrauchen. Wiederholungen sind die günstigste Lösung.

Wenn nichts ankommt

  • Der Test schlägt mit HTTP 400 fehl. Bei Weg 1 prüfe, ob Additional Headers "Content-Type": "application/json" enthält. Ohne diesen Header geht die Anfrage als Formulardaten raus.
  • HTTP 401. Der Header Token fehlt, oder der Schlüssel wurde widerrufen. Erstelle unter API-Schlüssel einen neuen.
  • Der Test kommt an, aber Ausfälle nicht. Öffne den Monitor und prüfe, ob die Benachrichtigung angehakt ist. Außerdem benachrichtigt Uptime Kuma bei der ersten Prüfung eines Monitors nicht, wenn dieser online ist. Ein neuer Monitor bleibt also ruhig, bis sich etwas ändert.
  • Weg 2 zeigt nichts. Öffne den Verlauf des Webhooks in der Konsole. Ist die Anfrage dort mit einem Fehler vorhanden, steht der Grund dabei: ungültiges JSON oder eine Vorlage, die eine leere Nachricht erzeugt hat. Wird gar nichts protokolliert, hat Uptime Kuma p4a.me nie erreicht. Du kannst auch Anfragen an den Webhook-Tester schicken, um genau zu sehen, was Uptime Kuma sendet.
  • Eine Wiederherstellung fehlt scheinbar. low-Pushes sind lautlos. Prüfe den Feed in der App.

FAQ

Welche Uptime-Kuma-Version braucht das?

Getestet wurde mit 2.5.8, der zum Schreibzeitpunkt neuesten Version. Auch Version 1.23.x hat den Webhook-Typ mit Custom Body und Additional Headers, und seine Vorlage bekommt dieselben Variablen msg, monitorJSON und heartbeatJSON. Ich habe den Body für Weg 1 mit der Template-Engine aus 1.23.16 gerendert und dasselbe JSON erhalten. Den vollständigen Durchlauf habe ich aber nur mit 2.5.8 gemacht.

Was passiert, wenn der Server mit Uptime Kuma ausfällt?

Dann sendet niemand die Meldung. Uptime Kuma kann seinen eigenen Ausfall nicht melden, also brauchst du etwas außerhalb davon, das es bemerkt, etwa einen Check von einem anderen Rechner oder einen gehosteten Monitor. Die Seite Uptime-Überwachung listet gehostete Monitore auf, die mit Pocket-Alert-Webhooks funktionieren.

Kann ich verschiedene Monitore an verschiedene Handys senden?

Ja, mit einem kostenpflichtigen Tarif. Lege pro Gruppe eine Benachrichtigung an, mit einer anderen device_id im Body (Weg 1), oder einen anderen Webhook mit eigenem Gerät (Weg 2), und aktiviere auf jedem Monitor die passende. Der kostenlose Tarif hat ein Gerät und einen Webhook, es gibt also nur ein Handy, an das du senden kannst.

Funktioniert das auch für Ping-, Port- und DNS-Monitore?

Ja. Der Body verwendet nur den Namen und die ID des Monitors sowie Status und Meldung des Heartbeats, und die haben alle Monitortypen. Manche Typen, Ping unter anderem, lassen die Meldung leer, wenn der Check erfolgreich ist; dann greift der Body auf Uptime Kumas eigenen Text zurück. Der Button verlinkt auf die Seite des Monitors in Uptime Kuma statt auf die geprüfte Adresse, daher funktioniert er auch, wenn die Adresse keine URL ist.

Ich nutze das schon für Proxmox. Kann es einen API-Schlüssel teilen?

Kann es, aber gib Uptime Kuma einen eigenen Schlüssel, damit das Widerrufen des einen nicht den anderen kaputt macht. Die Proxmox-Anleitung behandelt Backup- und Festplattenwarnungen aus demselben Homelab.

Erstelle ein kostenloses Konto, füge den Body in eine Webhook-Benachrichtigung ein, und lass den nächsten Ausfall dein Handy erreichen, während die Wiederherstellung leise im Feed wartet.

Artikel teilen