Ereignisse und Webhooks¶

Ihre eigenen Programme können verfolgen, was sich in OS ändert, ohne ständig alle Listen abzufragen. Jede Änderung an den Personen, den Einstellungen oder dem Dienst Ihrer Organisation wird als Ereignis festgehalten. Ihr Programm liest diese Ereignisse aus dem Feed oder erhält sie als signierten Webhook an einer Adresse, die Sie registriert haben.

Ein Ereignis ist keine Benachrichtigung. Eine Benachrichtigung ist eine Nachricht für Menschen, in ihrer Sprache. Ein Ereignis ist ein Verweis auf etwas, das sich geändert hat, gedacht für ein Programm.

Was ein Ereignis enthält¶

{"id": "evt_01JA...",
 "type": "directory.membership.deactivated",
 "organisation_id": "org_7Hq2...",
 "cursor": "1187",
 "created_at": "2026-10-17T09:14:03Z",
 "refs": {"membership_id": "mem_01J9...", "principal_kind": "person", "status": "deactivated"}}

Verweise, kein Inhalt. refs enthält IDs, Status und die Namen geänderter Felder. Nie einen Namen, eine E-Mail-Adresse, einen Betrag oder etwas, das jemand geschrieben hat. Möchte Ihr Programm mehr wissen, fragt es die Sache selbst bei OS ab, und OS entscheidet dann erneut, was es sehen darf.
Der Cursor ist eine Zahl als Text, je Organisation fortlaufend in der Reihenfolge nummeriert, in der OS die Ereignisse festgehalten hat.
Reihenfolge. Zwei Änderungen kurz nacheinander können in beiden Reihenfolgen festgehalten werden, und Webhooks können in beliebiger Reihenfolge ankommen. Sortieren Sie nach cursor und lesen Sie die Sache neu ab, wenn der aktuelle Stand zählt.

Welche Arten von Ereignissen es gibt, steht unter Ereignisse.

Der Feed oder ein Webhook¶

	Der Feed	Ein Webhook
Wie	Ihr Programm fragt `GET .../events?cursor=` ab	OS sendet jedes Ereignis an Ihre Adresse
Wann	wann Ihr Programm will, zum Beispiel jede Minute	innerhalb weniger Sekunden
Was Sie festhalten	den letzten Cursor, den Sie verarbeitet haben	nichts: OS versucht es erneut, bis es klappt
Verpasst	ab Ihrem letzten Cursor lesen	den Feed ab Ihrem letzten Cursor lesen

OS bewahrt Ereignisse sieben Tage auf. Fragen Sie den Feed mit einem Cursor ab, dessen nachfolgende Ereignisse schon weg sind, antwortet OS mit 410: Lesen Sie dann den Stand neu ein und beginnen Sie ohne Cursor.

Wer was sieht¶

Ein Webhook arbeitet im Namen eines Kontos Ihrer Organisation, meist eines Dienstkontos, und nie im Namen dessen, der ihn registriert hat. OS entscheidet bei jeder Zustellung erneut, ob dieses Konto das Ereignis sehen darf: Es braucht see auf event und see auf die Sache, um die es im Ereignis geht. Sieht das Konto ein Mitglied nicht, erhält der Webhook auch die Ereignisse über dieses Mitglied nicht. Eine solche Zustellung steht im Protokoll als übersprungen, damit Sie sehen können, warum sie nicht ankam.

Wer den Feed liest, sieht auf dieselbe Weise nur die Ereignisse, die er sehen darf.

Einen Webhook registrieren kann nur, wer write auf webhook hat, das Konto ändern darf und selbst alles hat, was dieses Konto hat. Ein Administrator (org-admin) hat das.

Wenn eine Adresse nicht antwortet¶

OS versucht eine fehlgeschlagene Zustellung erneut nach etwa 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden, 12 Stunden und 24 Stunden: acht Versuche in knapp zwei Tagen. Schlägt es fünfmal hintereinander fehl, heißt der Webhook fehlerhaft: OS sendet dann jeweils eine Zustellung und hält den Rest zurück. Klappt wieder eine, ist der Webhook wieder aktiv und der Rest folgt. Ist er drei Tage lang fehlerhaft, oder ist das Konto nicht mehr aktiv, wird er ausgeschaltet. Die Administratoren Ihrer Organisation erhalten bei beidem eine Benachrichtigung. Die Ereignisse bleiben im Feed stehen, und ein Administrator kann den Webhook wieder einschalten.

Antwortet eine Adresse mit 410, sagt sie damit, dass es sie nicht mehr gibt: OS schaltet den Webhook sofort aus.

Sicherheit¶

Jede Zustellung ist mit dem Geheimnis des Webhooks signiert. Prüfen Sie die Signatur, bevor Sie etwas mit dem Inhalt tun (so geht es).
OS sendet nur an https-Adressen mit einem Hostnamen, der im Internet erreichbar ist. Eine Adresse, die auf eine interne oder private Adresse führt, lehnt OS ab, beim Registrieren und bei jedem Versuch.
OS folgt keiner Weiterleitung und liest die Antwort Ihrer Adresse nicht.
Legen Sie kein Geheimnis in die Adresse: Wer den Webhook sehen darf, sieht die Adresse.

Webhooks sind erst eingeschaltet, wenn Artific sie für Ihre Umgebung eingeschaltet hat. Bis dahin antwortet OS auf das Registrieren mit 409; der Feed funktioniert.