So richten Sie signierte Webhook-Benachrichtigungen von einem Überwachungstool ein

Webhook-Benachrichtigungen sind der Integrationsklebstoff, der einen Verfügbarkeitsmonitor mit allem anderen verbindet: PagerDuty, Opsgenie, interne Vorfallsysteme, Ticket-Tracker, benutzerdefinierte Slack-Bots. Die grundlegende Mechanik ist einfach (Ihr Monitor POSTet JSON an Ihren Endpoint, wenn ein Vorfall auftritt). Die Details (Signaturüberprüfung, Wiederholungsverhalten, Idempotenz) sind dort, wo die Implementierung interessant wird. Dieser Leitfaden behandelt das praktische Setup.

Warum Webhooks statt E-Mail oder Slack

E-Mail und Slack funktionieren gut für Menschen. Webhooks funktionieren für Systeme. Drei Anwendungsfälle rechtfertigen das zusätzliche Setup.

Weiterleitung an ein Paging-Tool, das Ihre On-Call-Rotation ausführt (PagerDuty, Opsgenie). Betrieb eines internen Incident-Management-Systems, das Tickets öffnet, Slack-Threads erstellt und Runbooks automatisch ausführt. Auslösen von automatisierter Fehlerbehebung (Neustart eines Worker, Skalierung eines Clusters, Failover zu einer Backup-Region). Alle drei benötigen eine strukturierte Payload, wiederholungssichere Zustellung und Authentifizierung. Webhooks bieten alle drei; E-Mail und Slack bieten keine.

Die zu erwartende Payload-Struktur

Die meisten Überwachungstools senden eine ähnliche JSON-Payload bei Vorfällen. Die genauen Feldnamen variieren, aber vier Abschnitte sind Standard.

• event: «monitor.down» oder «monitor.up», damit Ihr Endpoint Öffnungen und Schließungen leiten kann.
• monitor: id, name, type, target, last status. Genug Kontext, um zu identifizieren, was kaputt ist.
• check: status code, response time, error message. Das Diagnosedetail.
• timestamp: ISO 8601, UTC. Wichtig für Bestellung und Deduplizierung.

HMAC-Signatur überprüfen

Jeder Webhook-Endpoint, der dem öffentlichen Internet ausgesetzt ist, benötigt eine Signaturüberprüfung. Ohne sie kann ein Angreifer, der Ihre URL errät, ein Ereignis «monitor down» vortäuschen und Ihre Fehlerbehebung, Paging und Support-Antwort auslösen. Mit HMAC-Überprüfung kann nur Ihr Überwachungstool gültige Payloads signieren.

Das Muster: das Überwachungstool sendet einen X-Monitorah-Signature-Header mit dem HMAC-SHA256 des rohen Request-Body, verschlüsselt mit einem gemeinsamen Geheimnis. Ihr Endpoint berechnet das HMAC des Body mit demselben Geheimnis neu, vergleicht (in konstanter Zeit) mit dem Header-Wert, lehnt bei Nichtübereinstimmung ab. Verwenden Sie die rohen Bytes des Body für das HMAC, nicht das geparste JSON: ein einziger Whitespace-Unterschied erzeugt eine andere Signatur.

Wiederholung und Idempotenz

Webhook-Zustellung folgt dem Best-Effort-Prinzip und ist nicht garantiert. Zwei Muster machen Ihren Endpunkt robust für Wiederholungen und teilweise Ausfälle.

• Wiederholungen elegant handhaben. Die meisten Monitore wiederholen eine 5xx-Antwort mit exponentiellem Backoff für bis zu 24 Stunden. Geben Sie 5xx zurück, wenn Sie das Ereignis nicht verarbeiten können; geben Sie 2xx zurück, wenn Sie es können.
• Ereignis-ID als Idempotenzschlüssel behandeln. Dieselbe Incident-Öffnung kann den Webhook während eines Netzwerkausfalls zweimal auslösen. Deduplizieren Sie, indem Sie die Ereignis-ID speichern und überspringen, wenn Sie sie bereits verarbeitet haben.
• Schnell antworten. Benötigen Sie weniger als 5 Sekunden, um 2xx zurückzugeben, auch wenn Ihre nachgelagerte Verarbeitung länger dauert. Verwenden Sie eine Job-Warteschlange, falls erforderlich.

Integration mit PagerDuty

PagerDuty akzeptiert einen allgemeinen Webhook über seine Events API v2. Der Ablauf: Ihr Monitoring-Tool sendet eine benutzerdefinierte JSON-Payload an Ihren Handler. Ihr Handler verifiziert das HMAC, ordnet die Payload dem erwarteten Schema von PagerDuty zu und sendet an den Events-Endpunkt von PagerDuty mit Ihrem Routing-Schlüssel.

Die Übersetzungsschicht ist der richtige Ort, um Deduplizierung, Eskalationsregeln und pro-Monitor-Routing-Schlüssel hinzuzufügen. Die Benutzeroberfläche von PagerDuty verwaltet die Rotation, sobald das Ereignis erfasst wurde. Halten Sie den Übersetzer einfach. Die saubere Version hat weniger als hundert Zeilen Code.

Ein einfacher Webhook-Handler in 20 Zeilen

Das Muster: POST empfangen, Header X-Monitorah-Signature extrahieren, HMAC-SHA256 auf den Rohtextkörper mit Ihrem Geheimnis anwenden und im Constant-Time-Vergleich mit dem Header vergleichen. Stimmen sie überein, JSON analysieren, nach Ereignis-ID deduplizieren und versenden. Andernfalls 401 zurückgeben ohne Verarbeitung. Dieser Handler ist der Baustein für jede Integration oben drauf: PagerDuty, Opsgenie, Slack Bots, interne Incident-Systeme. Sobald vorhanden, ist jede neue Integration nur ein paar Zeilen Dispatch-Logik und nichts mehr.