Ereignisse, Webhooks und Beobachtbarkeit für Integrationen
Was hat sich geändert
Jede Inhaltsänderung wird versioniert. Wählen Sie eine Version, um sie mit der vorherigen zu vergleichen.
Version 1 → 2
Aktualisierung5 Lektionen aktualisiertDauer
Inhaltliche Aktualisierung. Eingeschriebene Lernende wurden benachrichtigt.
Dauer von 13 auf 17 Minuten geändert.
Eine Webhook-Definition in Monosign ist an einen Audit-Typ gebunden. Jedes Audit dieses Typs erzeugt eine Ausführung, und der Webhook-Dienst sendet die Anfrage. Zwei Fragen kommen in jedem Projekt: Warum kam mein Test leer an, und was passiert, wenn die Nachrichtenwarteschlange ausfällt?
::diagram api-webhook-delivery
### Tokens stammen aus dem Audit
Auf dem Audit-Pfad liefert Monosign immer fünf Schlüssel sowie die Datenschlüssel dieses Audit-Typs:
| Token | Wert |
| --- | --- |
| `{{Audit.UserId}}` | Der Benutzer, um den es im Ereignis geht |
| `{{Audit.ActorUserId}}` | Der Benutzer, der die Aktion ausgeführt hat |
| `{{Audit.SessionId}}` | Die Sitzung |
| `{{Audit.ApplicationId}}` | Die Anwendung |
| `{{Audit.CreatedDate}}` | Wann das Audit geschrieben wurde |
Tokens werden in `URL`, `Headers` und `Body` ersetzt. Ein Token, das weder zu diesen fünf gehört noch ein Datenschlüssel des Audits ist, wird durch nichts ersetzt. Ein aus einem Beispiel kopierter Body mit `{{UserId}}` erreicht den Empfänger daher mit leerem Wert. Schreiben Sie `{{Audit.UserId}}`.
Eine kleine Definition für einen Anmelde-Feed sieht so aus:
```
Type: USER_LOGIN_SUCCESS
URL: https://siem.example/hook
Method: POST
Headers: {"X-Actor-Id": "{{Audit.ActorUserId}}"}
Body: {"user": "{{Audit.UserId}}", "at": "{{Audit.CreatedDate}}"}
```
### Was `Execute` beweist und was nicht
`Execute` sendet die Anfrage mit einem leeren Datensatz. Es beweist, dass die URL erreichbar ist, dass Methode und Header akzeptiert werden und dass der Empfänger rechtzeitig antwortet. Über Ihre Tokens beweist es nichts, weil jedes Token als leere Zeichenfolge ausgegeben wird. Um die Tokens zu testen, lösen Sie ein echtes Audit-Ereignis dieses Typs aus, etwa eine Anmeldung, und suchen Sie in den `Items` der Definition nach einer Zeile mit `Send Success`.
### Wiederholungen
Ein fehlgeschlagener Versand wird bis zu fünfmal versucht, mit einer festen Wartezeit von einer Sekunde zwischen den Versuchen. Danach wird die Zeile als `Max Try Reached` markiert und erscheint unter `Dead Letters`. Deshalb muss der Empfänger ein wiederholtes Ereignis als unschädlich behandeln.
### Wenn die Nachrichtenwarteschlange ausfällt
::diagram obs-webhook-outage
Im Normalbetrieb läuft die Ausführung über die Nachrichtenwarteschlange. Solange der Broker nicht nutzbar ist, stellt der **Service-Host** Webhooks in begrenzten Stapeln direkt aus der Datenbank zu. Die Zustellung läuft weiter, auch wenn Redis ausfällt.
Die praktische Folge betrifft das Netzwerk. Während des Ausfalls öffnet der Service-Host selbst die ausgehende Verbindung zu Ihrem Empfänger. An einem Standort mit Firewall-Regeln je Prozess oder Host braucht der Service-Host eine Ausgangsregel zum Webhook-Empfänger. Bleiben Ereignisse genau dann aus, wenn der Broker ausfällt, prüfen Sie zuerst diese Regel.
Management, System, Services, `Dead Letters` ist der Ort, an dem Arbeit, die vor der Zustellung stehen geblieben ist, auf einen Menschen wartet. Ein Integrationsingenieur muss wissen, was die Liste enthält, was sie auslässt und was jede Schaltfläche wirklich tut.
::diagram obs-dead-letters
### Was aufgeführt wird
| Art | Eine Zeile erscheint, wenn | Angezeigt |
| --- | --- | --- |
| `Notifications` | Das Versenden der Benachrichtigung selbst gescheitert ist und ihre Wiederholungen verbraucht sind | Die letzten 30 Tage |
| `User Provisions` | Eine Provisionierungszeile im Fehlerzustand ist, etwa nach 48 Stunden ohne Abschluss | Bis zu 200 Zeilen |
| `Webhooks` | Ein Webhook seine maximale Zahl von Versuchen erreicht hat | Bis zu 200 Zeilen |
Die Liste gehört immer zu dem Mandanten, an dem Sie angemeldet sind.
### Eine leere Liste ist kein Gesundheitsnachweis
Drei Grenzen machen einen ruhigen Tab zu einem schwachen Signal:
- Eine Benachrichtigung, deren Mail, SMS oder Push gescheitert ist, wird **nicht** aufgeführt. Der Fehler steht in der Verlaufszeile dieses Kanals, und die Benachrichtigung selbst endet trotzdem als `Completed`. Nur ein Fehler auf Versandebene legt eine Benachrichtigung hier ab.
- Sie sehen einen Mandanten und bei Benachrichtigungen nur die letzten 30 Tage.
- Die Seite alarmiert nicht, sendet keine Mail und überwacht nichts. Eine Zeile ist nur sichtbar, wenn jemand die Seite öffnet.
Behandeln Sie die Liste als Arbeitswarteschlange, die Sie regelmäßig durchsehen, und kombinieren Sie sie mit dem Kanalverlauf und der Überwachung der empfangenden Systeme.
### Was die Schaltflächen tun
| Art | `Requeue` | `Discard` |
| --- | --- | --- |
| Benachrichtigung | Zurück in den Wartezustand, mit neuer Ablaufzeit von 24 Stunden | Endgültig verworfen |
| Benutzerprovisionierung | Zurück in ihren Wartezustand, vom Provisionierungsdienst wieder aufgenommen | Endgültig verworfen, nichts wird gesendet |
| Webhook | Die Zeile verlässt die Liste mit zurückgesetztem Versuchszähler, wird aber nicht erneut gesendet | Endgültig verworfen |
Beide Schaltflächen wirken auf jeweils eine Zeile. Ein erneut eingereihtes Element kann wieder scheitern und in die Liste zurückkehren. Ein Discard behält die Zeile und ihren letzten Fehler in der Datenbank, lässt sich am Bildschirm aber nicht rückgängig machen.
Die Webhook-Zeile verdient Aufmerksamkeit: Weil ein erneut eingereihter Webhook nicht zugestellt wird, verwenden Sie `Requeue` nicht, um ein verlorenes Ereignis nachzuspielen. Lösen Sie das Geschäftsereignis erneut aus oder lassen Sie den Empfänger den aktuellen Zustand über die API abrufen.
### Wer es getan hat
Keine der beiden Aktionen schreibt Audit-Spalten in die Zeile. Jede schreibt eine Zeile in das Management-Protokoll:
```
Dead letter requeued: webhook 7d0c... by 41aa...
Dead letter discarded: userprovision 92be... by 41aa...
```
Die Zeile enthält die Art (`notification`, `userprovision` oder `webhook`), die Zeilen-ID und die Benutzer-ID. Für ein Discard ist diese Zeile der einzige Nachweis. Wenn ein Prüfer fragen könnte, wer eine Zeile ausgemustert hat, bewahren Sie die Management-Protokolle lange genug auf.
Monosign bietet auf den Anwendungen API und Management zwei Familien von Health-Endpunkten ohne Authentifizierung. Sie beantworten unterschiedliche Fragen, und die falsche Wahl führt entweder zu blinden Flecken oder zu unnötigen Neustarts.
### Die zwei Familien
| Endpunkt | Was er prüft | Antwort |
| --- | --- | --- |
| `GET /ping/hc` | Eine Checkliste: `Database`, `Mq`, `Cache`, `ServerGC`, `License` | 200 `{"IsHealthy":true}` oder 400 mit den fehlschlagenden Einträgen |
| `GET /ping/hc/mq` (nur API) | Eine Abhängigkeit; `db`, `cache` und weitere funktionieren genauso | Das Urteil dieser einen Prüfung |
| `GET /probes/ready` | Nur die Datenbank. Der Cache-Zustand wird gemeldet, aber nicht bewertet | 200 oder 503 `not ready` |
| `GET /probes/live`, `/probes/startup` | Für Orchestratoren | 200, solange der Prozess bedient |
### Welcher für welchen Verbraucher
- **Ein Orchestrator, der einen Container bei Fehlern neu startet**, sollte `/probes/ready` verwenden. Ein Broker-Problem macht `/ping/hc` ungesund, und der Neustart des API-Containers repariert keinen Broker. Readiness betrachtet nur die Datenbank und löst daher keine Neustarts für einen Fehler aus, den ein Neustart nicht beheben kann.
- **Ein Load Balancer** sollte das vollständige `/ping/hc` verwenden, bei dem jede fehlschlagende Prüfung `IsHealthy` umschaltet und der Knoten aus der Rotation fällt.
- **Ein Monitor für eine Abhängigkeit** sollte die gezielte Form verwenden, zum Beispiel `/ping/hc/mq`.
::diagram obs-health-probes
### Geben Sie dem Monitor mindestens sechs Sekunden
Die `Mq`-Prüfung ist ein echter Durchlauf durch den Broker mit einem Probe-Timeout von fünf Sekunden. Ein beeinträchtigter Broker lässt die gesamte Antwort so lange dauern. Ein externer Monitor mit einem Timeout unter sechs Sekunden meldet sein eigenes Timeout, bevor Monosign den eigentlichen Grund melden kann.
### Überwachung der Nachrichtenwarteschlange ab v2026.10
Mit v2026.10 haben sich zwei Dinge geändert. Health-Fehler werden pro Minute gezählt und auf der Seite `Status` als fehlerhafte Minuten pro Tag angezeigt. Und die Nachrichtenwarteschlange wird nicht mehr zentral geprüft, weil der Broker zu jedem Rechenzentrum gehört. Ein Monosign-Monitor, der den zentralen Dienst `mq` beobachtet, bleibt bei einem Broker-Ausfall daher stumm. Das `/ping/hc` jedes Knotens enthält weiterhin den Eintrag `Mq`. Richten Sie die Überwachung also auf die Knoten.
Wenn ein REST-Aufruf scheitert oder ein Push nicht ankommt, brauchen Sie das Protokoll der richtigen Komponente. Monosign bietet drei Wege dorthin, und jeder hat eine klare Grenze.
| Weg | Deckt ab | Grenze |
| --- | --- | --- |
| Container-Ausgabe | Jede Komponente, fortlaufend | Sie brauchen eine eigene Log-Pipeline |
| Management, System, `Logs` | Management und Service-Prozesse, die damit verbunden sind | Nicht API, nicht Account; nur im Arbeitsspeicher |
| Management, System, `Tracing & Log` | Die gewählten Anwendungen, für eine festgelegte Zahl von Minuten | Manche Anwendungen haben keinen Collector |
::diagram obs-log-paths
### Container-Ausgabe und JSON-Zeilen
Jeder Prozess schreibt sein Protokoll als Klartext nach stdout. Ab v2026.10 macht `MONOSIGN_LOG_FORMAT=json` an einer Komponente jede stdout-Zeile dieses Prozesses zu einem JSON-Objekt, genau das, was eine JSON-Lines-Pipeline erwartet. Drei Details zählen bei der Einrichtung:
- Die Variable wird je Komponente gelesen. Setzen Sie sie also an jedem Container, von dem Sie sammeln.
- Sie gilt **nur für stdout**. stderr bleibt unverändert, der Absturzbericht der Laufzeitumgebung kommt also weiter als Klartext. Eine Pipeline muss diese wenigen Zeilen vertragen.
- Ein anderer Wert als `json` oder `text` fällt mit einer Warnzeile auf Text zurück. Der Start scheitert daran nie.
### Die Seite Logs
Die Seite streamt Ereignisse des Management-Prozesses und von Service-Prozessen, deren `MONOSIGN_LOG_HUB_URL` auf Management zeigt. Die Anwendungen API und Account senden ihre Ereignisse nie dorthin, und die Kontrollkästchen unter `Apps` filtern nichts. Wenn Sie fehlgeschlagene REST-Aufrufe untersuchen, kann diese Seite die API-Seite nicht zeigen.
Die Ereignisse liegen im Arbeitsspeicher einer Management-Instanz, bis zu 100 000 Stück, und sind nach einem Neustart weg.
`Configure` enthält eine Einstellung, die sich verkehrt herum liest. `Default Level` **verwirft** Ereignisse auf oder unter der gewählten Stufe:
| `Default Level` | Was Sie sehen |
| --- | --- |
| `Verbose` | Alles oberhalb von Verbose, das Maximum, das die Seite zeigen kann |
| `Warning` (Standard) | Error und Fatal |
| `Error` | Nur Fatal |
Um Fehler zu sehen, muss die Stufe niedriger als Error sein. Die Einstellung filtert nur die Seite. Sie ändert nicht, was die Prozesse protokollieren.
### Tracing & Log
Ein Trace erfasst die vollständige Protokollausgabe der gewählten Serveranwendungen für `Duration` Minuten und bietet das Ergebnis als ein Zip an. Das ist das Werkzeug für die Anwendungen API und Account.
Wählen Sie nur Anwendungen, die antworten können. `Monosign - Access Gateway` und `Monosign - RADIUS Server` stehen in der Liste, haben aber keinen Collector. Ein Trace, der sie nennt, wird nie fertig: Er bleibt `Started`, und `Download` meldet, dass Anwendungen noch laufen. Holen Sie das Gesammelte mit `Download Partial` und lassen Sie die beiden beim nächsten Mal weg. `Force Start` und `Interval` im Formular werden gespeichert, aber nicht verwendet, und Traces werden von der Datenaufbewahrung nicht entfernt. Löschen Sie alte also selbst.
> Tipp: Gehen Sie von der Komponente aus, nicht vom Werkzeug. Für die Seite von API oder Account nutzen Sie `Tracing & Log` oder die Container-Ausgabe. Die Seite `Logs` kann nur Management und die damit verbundenen Dienstprozesse zeigen.
Monosync hat vier Signale. Jedes beantwortet eine Frage gut und schweigt zu anderen, und von einem Integrationsingenieur wird erwartet, dass er sie auseinanderhält.
| Signal | Frage, die es beantwortet | Was es nicht verrät |
| --- | --- | --- |
| `/ping/hc` | Läuft die Installation, und leben die Service-Knoten? | Ob eine bestimmte Integration funktioniert |
| `Integration Logs` | Was hat ein Lauf mit einem Datensatz getan? | Alles über Läufe hinweg oder außerhalb von Monosync |
| `Monitoring` | Ist eine Integration gescheitert oder läuft sie nicht mehr? | Nichts, wenn der Mailweg nicht konfiguriert ist |
| `Audits` | Wer hat die Konfiguration in der Weboberfläche geändert? | Änderungen über andere Wege |
### Die Health-Antwort hat zwei Felder
```
GET /ping/hc
{"IsHealthy":true,"InstanceCount":3}
```
`InstanceCount` ist die Zahl der Service-Knoten, die sich melden. Diese Knoten führen die Integrationen aus. Eine Antwort `{"IsHealthy":true,"InstanceCount":0}` ist weiterhin HTTP 200, und doch kann keine Integration laufen, etwa weil die Service-Rolle auf jedem Knoten deaktiviert ist. Eine Probe, die nur `IsHealthy` betrachtet, übersieht das. Alarmieren Sie also auch bei einer Anzahl von null.
### Einen Lauf lesen
Die Protokollseite führt vom Lauf zu seinen Aktionen, zu den Objekten, die eine Aktion berührt hat, und zu den geänderten Werten eines Objekts. Scheitert ein Job nur für einige Benutzer, beginnen Sie hier: Der Grund steht in der Objektzeile, in `Status`, `Message` und `Exception`, und Mapping-Fehler werden unter `Mapping error(s) found!` gesammelt.
Zwei Grenzen zählen für ein Security-Operations-Team:
- `Export All` exportiert die geänderten Werte des Laufs. Fehler exportiert es nicht.
- Monosync sendet seine Protokolle nirgendwohin. Ein SIEM oder jede laufübergreifende Sicht braucht eine schreibgeschützte Abfrage auf den Protokolltabellen. Lesen Sie sie, bevor die Protokollaufbewahrung die Zeilen löscht.
### Monitore brauchen die Monosign-API
Ein Monitor öffnet einen Vorfall, wenn eine Integration Fehler hat oder eine festgelegte Zeit nicht gelaufen ist, und sendet eine `[DOWN]`-Meldung, Erinnerungen und bei Erholung eine `[UP]`-Meldung. Monitore haben keine eigene Mailserver-Einstellung. Mail und Push laufen über die Monosign-API, die auf dem UI-Knoten mit `MONOSIGN_API_URL`, `MONOSIGN_APPID` und `MONOSIGN_APPKEY` konfiguriert wird.
Ist einer der drei Werte leer, wird der Versand übersprungen, der Vorfall aber trotzdem als gemeldet markiert. Diese Meldungen sind endgültig verloren. Nachdem Sie die Variablen ergänzt haben, erwarten Sie Mails nur für neue Zustandswechsel und Erinnerungen, und sagen Sie dem Betriebsteam, dass die früheren DOWN-Meldungen nicht mehr kommen.
::diagram obs-monitor-notify
### Eine leere Audits-Liste ist kein Beweis
Monosync schreibt eine Audit-Zeile für Konfigurationsänderungen in der Weboberfläche. Mehrere Wege schreiben keine:
- Änderungen über die REST-API v1, etwa eine Quelleneinstellung oder ein Variablenwert.
- Ein Import von Einstellungen.
- Commits für Anlegen und Aktualisieren in der Oberfläche selbst, wenn die Installation mit `MONOSYNC_COMMIT_DISABLE=true` läuft.
Wenn sich die Einstellungen einer Quelle über Nacht geändert haben und `Audits` nichts zeigt, lautet der Schluss nicht, dass niemand sie geändert hat. Prüfen Sie, wer den API-Schlüssel hat und ob ein Import gelaufen ist.