Trigger

Automatisierungen pro Monitor, die externe Systeme bei Statusübergängen oder Payload-Treffern aufrufen. Ausgehende Aufrufe werden validiert und begrenzt, um unsichere Ziele und außer Kontrolle geratene Schleifen zu verhindern.

TRIGGER-TYPEN

Webhook: festes JSON-Schema mit HMAC-SHA256-Signatur-Headern. Wähle dies, wenn der Empfänger das KEEPitALIVE-Format erwartet.
HTTP Request: vollständig anpassbare Methode, Header und Body-Vorlage mit Platzhaltervariablen. Wähle dies für maßgeschneiderte Integrationen.
Notify: sendet eine Benachrichtigung über deine konfigurierten Alarmkanäle (E-Mail, Discord, Slack usw.) mit einer benutzerdefinierten Titel-/Body-Vorlage.
Incident: öffnet einen Ausfall-/Herabstufungs-Vorfall, wenn eine Payload-Bedingung zutrifft, und löst ihn automatisch auf, wenn ein späteres Ereignis die Bedingung aufhebt (oder wenn du den Trigger deaktivierst/löschst). Eine vollständig stumme Quelle löst sich nicht automatisch auf - siehe Bedingungen.

Abschnitt Trigger-Grundlagen mit den vier Typen: Webhook, HTTP Request, Benachrichtigung und Vorfall — Wähle zuerst den Typ - er entscheidet, was der Trigger beim Auslösen tut.

EREIGNISSE

Neun Ereignisse: down, recovered, degraded, flapping_start, flapping_stop, maintenance_start, maintenance_end, signal und payload. signal löst für Event-Receiver-Heartbeat-Beats aus. payload löst für Prüfungen aus, die ein Antwort-Payload erfasst haben, insbesondere API-Monitore.

VORLAGENVARIABLEN

Verwende diese in HTTP-Request-Body/-Headern/-URL und Notify-Titelvorlagen:

Verfügbare Platzhalter

{{monitor.id}}     {{monitor.ref}}     {{monitor.name}}    {{monitor.url}}     {{monitor.type}}
{{event.id}}       - stable per-fire id (same value across the retry; use it to dedupe)
{{event.type}}     {{event.status}}    {{event.latency_ms}}
{{event.status_code}}  {{event.error}}  {{event.timestamp}}
{{check.id}}       - id of the originating check (omitted for synthetic events)
{{payload}}        - full check payload as raw string
{{payload.KEY}}    - dot-path into the JSON payload (e.g. {{payload.status}})

Hinweis: monitor.id und monitor.ref lösen beide zur öffentlichen Monitor-Referenz auf - niemals zu einer internen Datenbank-ID. Richte deine nachgelagerten Systeme darauf aus.

HTTP-Request-Body-Vorlage (JSON)

{
  "source": "keepitalive",
  "monitor": "{{monitor.name}}",
  "event": "{{event.type}}",
  "status": "{{event.status}}",
  "latency_ms": "{{event.latency_ms}}",
  "error": "{{event.error}}",
  "at": "{{event.timestamp}}"
}

BEDINGUNGEN

Trigger können das Auslösen mit einem Ausdruck gegen das gespeicherte Prüf-Payload steuern. Grammatik: ==, !=, >, <, >=, <=, contains, exists, and, or, not, Klammern, Punktpfade. Beispiel: payload.failed_jobs > 0 and payload.status == "error". Incident-Trigger erfordern eine Bedingung. Sie öffnen den Vorfall, solange der Ausdruck zutrifft, und lösen ihn auf, wenn der Ausdruck nicht mehr zutrifft. So funktioniert die Auflösung: Der Vorfall löst sich automatisch auf, wenn eine spätere Prüfung oder ein Payload denselben Trigger neu auswertet und der Ausdruck nun falsch ist. Er schließt auch sofort, wenn du den Trigger deaktivierst oder löschst. Wichtig: Stille ist keine Wiederherstellung. Sendet die Quelle überhaupt keine Payloads/Heartbeats mehr, gibt es kein Ereignis, das die Bedingung aufhebt, sodass der Vorfall offen bleibt, bis ein neues Ereignis eintrifft oder du ihn manuell auflöst. Das ist beabsichtigt - wir behandeln "keine Daten" niemals als "wiederhergestellt", denn für eine Payload-/Signal-Quelle kann Stille der eigentliche Ausfall sein.

Was das Payload enthält, je Monitortyp

Heartbeat / event receiver - your posted JSON stays at the top:
  payload.failed_jobs, payload.status
  What we observed sits under beat, so it cannot shadow yours:
  payload.beat.received_at, payload.beat.exit_code,
  payload.beat.duration_ms
  (those three are also copied flat when you do not use the name)

API monitor - the response is wrapped:
  payload.body.<what the server returned>
  payload.status_code, payload.headers, payload.assertions

So an API check of a status endpoint reads
  payload.body.status.indicator - not payload.status.indicator.

Bedingung für Vorfall-Automatisierung

Open degraded incident when:
payload.failed_jobs > 0 or payload.status == "error"

Auto-resolves when a later event makes that expression false,
or when you disable/delete the trigger.
A source that goes fully silent will NOT auto-resolve.

WEBHOOK-PAYLOAD-FORMAT

Webhook-Trigger senden diesen festen JSON-Body per POST. Richte deinen Handler auf event_id (Deduplizierung) und monitor.ref (Identität) aus:

POST-Body

{
  "event_id": "9f2c1ab4e5d6...",   // stable per fire, repeats on retry
  "event": "down",
  "monitor": {
    "id": "mon_abc123", "ref": "mon_abc123",
    "name": "API", "url": "https://api.example.com", "type": "http"
  },
  "check": {
    "id": 84213, "status": "down",
    "latency_ms": 234, "status_code": 503, "error": "...",
    "payload": { }
  },
  "timestamp": "2026-06-27T12:00:00Z"
}

SIGNATURPRÜFUNG (WEBHOOK)

Wenn ein Webhook-Trigger ein Secret hat, trägt jede Zustellung X-Timestamp und X-Signature-256. Berechne neu und vergleiche, um gefälschte Aufrufe abzulehnen:

Verifizieren (Pseudocode)

signed   = X-Timestamp + "." + raw_request_body
expected = "sha256=" + hex(hmac_sha256(secret, signed))
reject unless constant_time_equals(expected, X-Signature-256)
// optional: reject if X-Timestamp is older than a few minutes

ZUSTELLUNGSSEMANTIK

Idempotenz: X-KEEPitALIVE-Event-ID (auch event_id im Body / {{event.id}}) wird einmal pro Auslösung erzeugt und über Wiederholungen hinweg wiederverwendet. Dedupliziere darauf, damit eine Wiederholung, die nach einem langsamen ersten Versuch eintrifft, nicht doppelt verarbeitet wird.
Wiederholungsrichtlinie: Netzwerk-Trigger können 0-3 Mal mit einer Verzögerung von 5-600 Sekunden wiederholen. Notify-Trigger wiederholen nicht, um doppelte, für den Nutzer sichtbare Benachrichtigungen zu vermeiden.
Weiterleitungen werden NICHT gefolgt: eine 3xx-Antwort zählt als Zustellungsfehler. Richte die URL auf das endgültige Ziel.
Schleifenbrecher: ausgehende Zustellungen tragen X-KEEPitALIVE-Depth. Ein Beat, der in einen Event-Receiver zurückgesendet wird, propagiert depth+1, und Netzwerk-Trigger stoppen bei Tiefe 3 - so sind Trigger -> Event-Receiver-Ketten auf 3 Sprünge begrenzt.

INTEGRATIONSREZEPTE

n8n / Make / Zapier: erstelle einen Webhook (n8n) oder einen Custom-Webhook-Catch-Hook (Make/Zapier) und füge dessen URL in einen HTTP-Request- oder Webhook-Trigger ein. Prüfe bei Webhook-Triggern X-Signature-256 in einem Function-/Code-Schritt, bevor du handelst; verzweige nach {{event.type}} und dedupliziere auf event_id.

Cloudflare-Cache-Leerung (HTTP-Request-Trigger)

Method: POST
URL:    https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache
Headers: Authorization: Bearer <API_TOKEN>
         Content-Type: application/json
Body:   { "purge_everything": true }
// Tip: gate on {{event.type}} == recovered to purge after a deploy recovers.

Home-Assistant-Webhook (HTTP-Request-Trigger)

Method: POST
URL:    https://<HA_HOST>/api/webhook/<WEBHOOK_ID>
Body:   { "monitor": "{{monitor.name}}", "status": "{{event.status}}",
          "event": "{{event.type}}", "event_id": "{{event.id}}" }

Generischer "Dienst neu starten"-Webhook

Method: POST
URL:    https://ops.example.com/hooks/restart
Headers: X-Auth-Token: <TOKEN>
Body:   { "service": "{{monitor.name}}", "reason": "{{event.error}}",
          "ref": "{{monitor.ref}}", "event_id": "{{event.id}}" }
// Make the receiver idempotent on event_id so a retry never double-restarts.

SICHERHEIT

Der Schutzschalter deaktiviert einen Trigger nach 10 aufeinanderfolgenden Fehlern (der Eigentümer erhält eine In-App-Benachrichtigung).
Flatter-Richtlinie: dieselbe 4-in-10-Min-Regel gilt pro Trigger.
Notify-Trigger protokollieren ein Zustellungsergebnis pro Kanal (zugestellt / teilweise / fehlgeschlagen) im Ausführungsprotokoll.
Das Webhook-Secret wird einmal beim Erstellen/Rotieren angezeigt; in allen folgenden Antworten ist es geschwärzt.