Webhook-Alarme: Payload, Header und Wiederholungen

Neben E-Mail und der Glocke in der App kann Pingsured einen Alarm als HTTP-Anfrage an eine URL Ihrer Wahl senden – an Ihr Incident-Tool, eine Chat-Integration, eine Automatisierungsplattform oder einen eigenen Endpunkt. Webhooks gibt es ab dem Team-Tarif. Eingerichtet werden sie von Eigentümern oder Managern des Kontos, für einen einzelnen Ping oder als Standard für alle Pings des Kontos.

Die Anfrage

Jeder Alarm ist ein POST mit JSON-Inhalt:

die URL muss https verwenden;
Content-Type: application/json;
User-Agent: Pingsured-Alarm/1;
bis zu 3 Weiterleitungen werden verfolgt;
Ihr Endpunkt hat 10 Sekunden Zeit, mit einem 2xx-Status zu antworten.

Adressen in privaten, Loopback- oder Link-Local-Netzen werden abgelehnt – auch dann, wenn ein öffentlicher Hostname auf eine solche Adresse zeigt oder eine Weiterleitung dorthin führt.

Die Payload

Feld	Bedeutung
`event`	`alarm.fired`, bei „Test senden“ `alarm.fired.test`
`version`	Version der Payload, derzeit `1`
`account_id`	das Konto, zu dem der Ping gehört
`task_id`	die ID des Pings
`task_name`	der Name des Pings, wie er in der App steht
`channel`	immer `webhook`
`trigger`	die Regel, die ausgelöst hat, etwa `first_error` oder `first_ok`
`result.status`	der aktuelle Status: `ok`, `warning`, `error` oder `unknown`
`result.prev_status`	der Status vor dieser Änderung, falls es einen gab
`result.started_at`	wann die Prüfung lief, die dieses Ergebnis lieferte, in ISO 8601 (UTC)
`result.location`	der Standort, dessen Prüfungen den Alarm ausgelöst haben, etwa `de` oder `us-west`

Fällt eine Website aus, sieht der Alarm typischerweise so aus:

event: alarm.fired
trigger: first_error
result.status: error, result.prev_status: ok

Ist sie wieder erreichbar, kommt derselbe Alarm mit trigger first_ok und vertauschten Statuswerten.

Header für Routing und Duplikaterkennung

X-Pingsured-Event wiederholt den Event-Namen, damit Sie Alarme weiterleiten können, ohne den Inhalt zu parsen.
X-Pingsured-Event-Version wiederholt die Version der Payload.
X-Pingsured-Delivery kennzeichnet die Zustellung. Bei einer Wiederholung bleibt der Wert gleich – speichern Sie ihn und ignorieren Sie eine zweite Anfrage mit einer bereits verarbeiteten ID.

Wiederholungen

Antwortet Ihr Endpunkt nicht rechtzeitig, ist er nicht erreichbar oder antwortet er mit 408, 425, 429 oder einem 5xx-Status, wird die Zustellung wiederholt – insgesamt fünf Versuche, im Abstand von 30 Sekunden, 5 Minuten, 30 Minuten und 2 Stunden. Jede andere 4xx-Antwort gilt als endgültig und wird nicht wiederholt, ebenso wenig eine Zustellung an eine URL, die schon vor dem Senden abgelehnt wird (einfaches http, eine private Adresse, zu viele Weiterleitungen).

Wann Webhooks gesendet werden

Ein Webhook folgt denselben Regeln wie jeder andere Alarmkanal:

Welche Änderungen. Empfohlen ist ein Alarm beim ersten Fehler und bei der Wiederherstellung. Sie können sich auch bei jedem fehlgeschlagenen Ergebnis alarmieren lassen.
Ab wie vielen Fehlern. Eine Schwelle wie „3 der letzten 5 Ergebnisse fehlerhaft“ verhindert, dass eine einzelne langsame Antwort jemanden weckt. Alarm- und Wiederherstellungsschwelle stellen Sie getrennt ein.
Wie oft. Wiederholte Alarme für denselben Ping und Kanal werden 15 Minuten lang zurückgehalten; ein Statuswechsel wird immer sofort gesendet.
Von wo. Jeder Standort, von dem aus ein Ping geprüft wird, wird für sich bewertet, und ein Fehler an einem davon löst den Alarm für den Ping aus.

Noch nicht verfügbar

Anfragen werden nicht signiert. Verwenden Sie bis dahin eine URL mit schwer zu erratendem Pfad oder Token und betrachten Sie X-Pingsured-Delivery als Kennung, nicht als Herkunftsnachweis.
Pro Ping gibt es nur eine Webhook-URL, dazu einen kontoweiten Standard.