Dieses Dokument wurde mithilfe automatisierter maschineller Übersetzungstechnologie übersetzt. Wir bemühen uns um korrekte Übersetzungen, übernehmen jedoch keine Gewähr für die Vollständigkeit, Richtigkeit oder Zuverlässigkeit der übersetzten Inhalte. Im Falle von Abweichungen ist die englische Originalversion maßgebend und stellt den verbindlichen Text dar.

Webhook

Webhooks sind benutzerdefinierte HTTP-Callbacks, die Sie definieren und ausführen. Sie können jede erforderliche Aktion ausführen, wenn eine Benachrichtigung geöffnet oder geschlossen wird. Zum Beispiel durch das Erstellen eines Tickets in einem Ticketsystem, das von SUSE Observability nicht nativ unterstützt wird. Oder indem Sie die Benachrichtigungsnachrichten einfach in einen S3-Bucket für zukünftige Referenz schreiben.

Der Webhook-Kanal sendet die Benachrichtigungsdaten als JSON über HTTP.

Einen Webhook konfigurieren

Um einen Webhook zu konfigurieren, füllen Sie die Felder aus:

URL - geben Sie die URL des Webhook-Endpunkts ein. Die URL muss prozentkodiert werden, wenn sie Sonderzeichen enthält.
Geheimer Token - ein geheimer Token, den SUSE Observability in jeder Anfrage einfügt, um ihn zu validieren.
Metadaten - fügen Sie zusätzliche Schlüssel/Wert-Paare hinzu, die im Payload enthalten sind. Dies kann verwendet werden, wenn derselbe Endpunkt mehrere SUSE Observability-Webhooks verarbeitet und zusätzliche Informationen benötigt.
SSL-Überprüfung aktivieren - (standardmäßig aktiviert) aktivieren Sie die Validierung des SSL-Zertifikats. Deaktivieren Sie dies nur, wenn Sie selbstsignierte Zertifikate oder von SUSE Observability nicht unterstützte Zertifizierungsstellen verwenden.

Wählen Sie schließlich "Kanal hinzufügen". Der Webhook-Kanal wird rechts angezeigt. Um zu testen, ob der Webhook funktioniert, senden Sie eine Testnachricht, indem Sie auf die Schaltfläche "Test" klicken.

Webhook-Anfragen und Payload

Der Webhook-Kanal sendet Daten als HTTP-POST-Anfragen. Der Endpunkt und die Payload sind in einer OpenAPI-Spezifikation dokumentiert.

Beispiel für eine Payload für eine Anfrage zum Öffnen einer Benachrichtigung

{
    "component": {
        "identifier": "urn:kubernetes:/k8s-demo-cluster:sock-shop:service/catalogue",
        "link": "https://play.stackstate.com/#/components/urn%3Akubernetes%3A%2Fk8s-demo-cluster%3Asock-shop%3Aservice%2Fcatalogue?timeRange=1702624556757_1702646156757&timestamp=1702635356757",
        "name": "catalogue",
        "tags": [
            "app.kubernetes.io/component:catalogue",
            "app.kubernetes.io/instance:sock-shop",
            "app.kubernetes.io/managed-by:Helm",
            "app.kubernetes.io/name:sock-shop",
            "app.kubernetes.io/version:0.3.5",
            "cluster-name:k8s-demo-cluster",
            "cluster-type:kubernetes",
            "component-type:kubernetes-service",
            "domain:business",
            "extra-identifier:catalogue",
            "helm.sh/chart:sock-shop",
            "name:catalogue",
            "namespace:sock-shop",
            "service-type:ClusterIP",
            "stackpack:kubernetes"
        ],
        "type": "service"
    },
    "event": {
        "state": "CRITICAL",
        "title": "HTTP - response time - is above 3.0 seconds",
        "triggeredTimeMs": 1702635356757,
        "type": "open"
    },
    "monitor": {
        "identifier": "urn:stackpack:kubernetes-v2:shared:monitor:kubernetes-v2:http-response-time",
        "link": "https://play.stackstate.com/#/monitors/urn%3Astackpack%3Akubernetes-v2%3Ashared%3Amonitor%3Akubernetes-v2%3Ahttp-response-time",
        "name": "HTTP - response time - is above 3 seconds",
        "tags": []
    },
    "notificationConfiguration": {
        "identifier": "urn:system:default:notification-configuration:testing-2",
        "link": "https://play.stackstate.com/#/notifications/urn%3Asystem%3Adefault%3Anotification-configuration%3Atesting-2",
        "name": "Test Notification"
    },
    "notificationId": "836f628c-1258-4500-b1c7-23884e00f439",
    "metadata": {
        "team": "Team A"
    }
}

Die Abschnitte in der open Payload sind:

Komponente: die SUSE Observability-Komponente, auf die die Benachrichtigung zutrifft. Dies umfasst den Namen, die Kennung, den Typ und die Tags der Komponente. Es enthält auch einen Link zur SUSE Observability-Benutzeroberfläche, der die Komponente zum Zeitpunkt der Änderung des Gesundheitszustands öffnet.
Ereignis: das Ereignis, das diese Benachrichtigung ausgelöst hat. Es kann entweder vom Typ open oder close sein (siehe nächster Abschnitt). Ein open Zustand bedeutet, dass der Monitor sich weiterhin in einem kritischen (oder abweichenden) Zustand für die angegebene Komponente befindet. Ein close Zustand bedeutet, dass der Monitor zuvor geöffnet war, das Problem jedoch behoben wurde. Der Zustand und die ausgelöste Zeit sind enthalten. Ebenfalls enthalten ist ein title, der eine kurze Beschreibung des Problems darstellt, wie sie vom Monitor bereitgestellt wird; es ist der gleiche Titel, der auf der Übersichtsseite der Komponente angezeigt wird, und kann sich von dem Namen des Monitors unterscheiden und detaillierter sein.
Monitor: der Monitor, der die Benachrichtigung ausgelöst hat. Neben dem Namen des Monitors sind auch Tags und die Kennung sowie ein Link enthalten. Der Link öffnet den Monitor in der SUSE Observability UI.
Benachrichtigungskonfiguration: Die Benachrichtigungskonfiguration für diese Benachrichtigung. Beinhaltet einen Namen, eine Kennung und einen Link. Der Link öffnet die Benachrichtigungskonfiguration in der SUSE Observability UI.
Benachrichtigungs-ID: Eine eindeutige Kennung für diese Benachrichtigung. Siehe auch den Lebenszyklus der Benachrichtigung
Metadata: Es ist möglich, Metadaten für einen Webhook-Kanal anzugeben. Die Metadaten werden hier als eine Menge von Schlüssel/Wert-Paaren eins zu eins wiedergegeben.

Beispielpayload für eine Anfrage zum Schließen einer Benachrichtigung

{
    "component": {
        "identifier": "urn:kubernetes:/gke-demo-dev.gcp.stackstate.io:sock-shop:service/catalogue",
        "link": "https://stac-20533-webhook-channel-management-api.preprod.stackstate.io/#/components/urn%3Akubernetes%3A%2Fgke-demo-dev.gcp.stackstate.io%3Asock-shop%3Aservice%2Fcatalogue?timeRange=1702624556757_1702646156757&timestamp=1702635356757",
        "name": "catalogue",
        "tags": [
            "app.kubernetes.io/component:catalogue",
            "app.kubernetes.io/instance:sock-shop",
            "app.kubernetes.io/managed-by:Helm",
            "app.kubernetes.io/name:sock-shop",
            "app.kubernetes.io/version:0.3.5",
            "cluster-name:gke-demo-dev.gcp.stackstate.io",
            "cluster-type:kubernetes",
            "component-type:kubernetes-service",
            "domain:business",
            "extra-identifier:catalogue",
            "helm.sh/chart:sock-shop",
            "name:catalogue",
            "namespace:sock-shop",
            "service-type:ClusterIP",
            "stackpack:kubernetes"
        ],
        "type": "service"
    },
    "event": {
        "reason": "HealthStateResolved",
        "type": "close"
    },
    "monitor": {
        "identifier": "urn:stackpack:kubernetes-v2:shared:monitor:kubernetes-v2:http-response-time",
        "link": "https://stac-20533-webhook-channel-management-api.preprod.stackstate.io/#/monitors/urn%3Astackpack%3Akubernetes-v2%3Ashared%3Amonitor%3Akubernetes-v2%3Ahttp-response-time",
        "name": "HTTP - response time - is above 3 seconds",
        "tags": []
    },
    "notificationConfiguration": {
        "identifier": "urn:system:default:notification-configuration:testing-2",
        "link": "https://stac-20533-webhook-channel-management-api.preprod.stackstate.io/#/notifications/urn%3Asystem%3Adefault%3Anotification-configuration%3Atesting-2",
        "name": "Test Notification"
    },
    "notificationId": "836f628c-1258-4500-b1c7-23884e00f439",
    "tags": {
        "team": "Team A"
    }
}

Die Abschnitte im close Payload sind die gleichen wie im open Payload, mit Ausnahme des event. Der type ist jetzt close und es gibt nur ein reason Feld, das angibt, warum die Benachrichtigung geschlossen wurde. Der Wert in diesem Feld ist ein enum, die OpenAPI-Spezifikation dokumentiert die möglichen Werte.

Lebenszyklus der Benachrichtigung

Wie aus dem Payload ersichtlich ist, wird jede Benachrichtigung eindeutig durch ihre notificationId identifiziert. Es ist möglich, sogar üblich, mehr als eine Nachricht für die gleiche Benachrichtigung zu erhalten, aber sie werden immer gemäß diesem Lebenszyklus gesendet.

Eine Benachrichtigung wird zuerst erstellt, wenn sich der Überwachungsstatus auf abweichend oder kritisch ändert (ob abweichend anwendbar ist, hängt von den Benachrichtigungseinstellungen ab). Eine Nachricht mit dem Ereignistyp open wird an den Webhook gesendet.

Eine Benachrichtigung kann aktualisiert werden, wenn sich die state oder die title im Ereignis ändern. Änderungen an der Komponente und anderen Teilen der Nachricht werden einbezogen, aber für sich allein werden sie keine Aktualisierung auslösen. Eine Aktualisierung der Benachrichtigung sendet ebenfalls eine Nachricht mit dem Ereignistyp open an den Webhook. Die Nachricht wird das gleiche notificationId haben, das verwendet werden kann, um die Daten im externen System zu aktualisieren (anstatt eine neue Benachrichtigung zu erstellen).

Schließlich wird eine Benachrichtigung geschlossen, wenn sich der Überwachungsstatus wieder in einen nicht kritischen (oder abweichenden) Zustand ändert. Eine Nachricht mit dem Ereignistyp close wird an den Webhook gesendet. Dies ist auch das letzte Mal, dass das spezifische notificationId verwendet wird.

Beachten Sie, dass eine Benachrichtigung aus anderen Gründen als einer Änderung des Gesundheitszustands sowohl geöffnet als auch geschlossen werden kann:

Ein Tag wird einer Komponente oder einem Monitor hinzugefügt. Dies kann dazu führen, dass einige kritische Gesundheitszustände von Monitoren die Auswahlkriterien in einer Benachrichtigungskonfiguration erfüllen und entsprechende Benachrichtigungen geöffnet werden.
Aus demselben Grund kann das Entfernen eines Tags von einer Komponente oder einem Monitor eine Benachrichtigung schließen, auch wenn der Gesundheitszustand weiterhin kritisch ist.
Änderungen an der Benachrichtigungskonfiguration selbst können ebenfalls dazu führen, dass viele neue Benachrichtigungen geöffnet oder geschlossen werden.

Validieren Sie die Anfragen

Das geheime Token, das in der Kanalkonfiguration angegeben ist, wird in den Webhook-Anfragen im X-StackState-Webhook-Token Header enthalten. Ihr Webhook-Endpunkt kann den Wert überprüfen, um zu verifizieren, dass die Anfragen legitim sind.

Wiederholungen

Der Webhook-Kanal wird Anfragen für eine Benachrichtigung erneut versuchen, bis er eine Status 200 OK-Antwort erhält (der Inhalt der Antwort wird ignoriert). Wenn der Webhook die Nachricht nicht verarbeiten kann (zum Beispiel, weil eine Datenbank gerade nicht erreichbar ist), kann er einfach mit einem Statuscode 500 antworten. SUSE Observability wird die gleiche Nachricht innerhalb weniger Sekunden erneut senden, in der Hoffnung, dass das Problem jetzt behoben ist.

Wenn eine Benachrichtigung aktualisiert oder geschlossen wurde, wird die alte Nachricht jedoch verworfen und die neue, aktualisierte Nachricht wird gesendet und erneut versucht, bis sie erfolgreich ist.

Beispiel-Webhook

Um zu testen, wie Webhooks funktionieren, können Sie dieses einfache Python-Skript verwenden, das einen HTTP-Server startet und die empfangene Payload auf die Standardausgabe schreibt.

Speichern Sie dieses Python-Skript als webhook.py:

from http.server import HTTPServer, BaseHTTPRequestHandler
import json
import sys

class WebhookHTTPRequestHandler(BaseHTTPRequestHandler):

 def do_POST(self):
     content_len = int(self.headers.get('content-length', 0))
     notification = json.loads(self.rfile.read(content_len))
     print("Notification received: ", json.dumps(notification, indent = 2))
     self.send_response(200)
     self.end_headers()

httpd = HTTPServer(('', int(sys.argv[1])), WebhookHTTPRequestHandler)
httpd.serve_forever()

Führen Sie den Webhook-Server auf einem ungenutzten Port (zum Beispiel 8000) aus: python3 webhook.py 8000
Konfigurieren Sie den Webhook in SUSE Observability mit der URL für Ihren Webhook-Server http://webhook.example.com:8000
Klicken Sie test im Webhook-Kanal

Die URL für Ihren Webhook muss von SUSE Observability zugänglich sein, daher reicht eine localhost-Adresse oder eine lokale IP-Adresse nicht aus.

Das Beispiel authentifiziert die Anfrage nicht, was durch die Überprüfung des Wertes des Token-Headers hinzugefügt werden kann.

Anstatt dies von Hand zu implementieren, ist es auch möglich, die OpenAPI-Spezifikation zu verwenden, um eine Serverimplementierung in einer der vom OpenAPI Generators-Projekt unterstützten Sprachen zu generieren.

Verwandt

Fehlerbehebung