Gebeurtenissen en webhooks¶

Je eigen programma's kunnen bijhouden wat er in OS verandert zonder steeds alle lijsten op te vragen. Elke wijziging aan de mensen, de instellingen of de dienst van je organisatie wordt vastgelegd als een gebeurtenis. Je programma leest die gebeurtenissen uit de feed, of ontvangt ze als een ondertekende webhook op een adres dat je hebt geregistreerd.

Een gebeurtenis is geen melding. Een melding is nieuws voor mensen, in hun taal. Een gebeurtenis is een verwijzing naar iets dat veranderde, bedoeld voor een programma.

Wat een gebeurtenis bevat¶

{"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"}}

• Verwijzingen, geen inhoud. refs bevat id's, statussen en de namen van gewijzigde velden. Nooit een naam, een e-mailadres, een bedrag of iets dat iemand schreef. Wil je programma meer weten, dan vraagt het het ding zelf op bij OS, en OS beslist dan opnieuw wat het mag zien.
• De cursor is een getal als tekst, per organisatie doorlopend genummerd in de volgorde waarin OS de gebeurtenissen vastlegde.
• Volgorde. Twee wijzigingen vlak na elkaar kunnen in beide volgordes worden vastgelegd, en webhooks kunnen in elke volgorde aankomen. Sorteer op cursor, en lees het ding op als de huidige stand ertoe doet.

Welke soorten gebeurtenissen er zijn, staat in Gebeurtenissen.

De feed of een webhook¶

OS bewaart gebeurtenissen zeven dagen. Vraag je de feed met een cursor waarvan de volgende gebeurtenissen al weg zijn, dan antwoordt OS 410: lees dan de stand opnieuw in en begin zonder cursor.

Wie wat ziet¶

Een webhook werkt namens een account van je organisatie, meestal een serviceaccount, en nooit namens wie hem registreerde. OS beslist bij elke aflevering opnieuw of dat account de gebeurtenis mag zien: het moet see op event hebben, en see op het ding waar de gebeurtenis over gaat. Ziet het account een lid niet, dan krijgt de webhook ook de gebeurtenissen over dat lid niet. Zo'n aflevering staat in het logboek als overgeslagen, zodat je kunt zien waarom ze niet aankwam.

Wie de feed leest, ziet op dezelfde manier alleen de gebeurtenissen die hij mag zien.

Een webhook registreren kan alleen wie write heeft op webhook, het account mag wijzigen en zelf alles heeft wat dat account heeft. Een beheerder (org-admin) heeft dat.

Als een adres niet antwoordt¶

OS probeert een mislukte aflevering opnieuw na ongeveer 1 minuut, 5 minuten, 30 minuten, 2 uur, 6 uur, 12 uur en 24 uur: acht pogingen in bijna twee dagen. Mislukt het vijf keer achter elkaar, dan heet de webhook falend: OS stuurt dan één aflevering tegelijk en houdt de rest vast. Lukt er weer een, dan is de webhook weer actief en volgt de rest. Is hij drie dagen falend, of is het account niet meer actief, dan wordt hij uitgeschakeld. De beheerders van je organisatie krijgen bij beide een melding. De gebeurtenissen blijven in de feed staan, en een beheerder kan de webhook weer inschakelen.

Een adres dat 410 antwoordt, zegt dat het weg is: OS schakelt de webhook meteen uit.

Veiligheid¶

• Elke aflevering is ondertekend met het geheim van de webhook. Controleer de handtekening voordat je iets met de inhoud doet (hoe).
• OS stuurt alleen naar https-adressen met een hostnaam die op internet uitkomt. Een adres dat uitkomt op een intern of privé-adres weigert OS, bij het registreren en bij elke poging.
• OS volgt geen doorverwijzing en leest het antwoord van je adres niet.
• Zet geen geheim in het adres: wie de webhook mag zien, ziet het adres.

Webhooks staan pas aan wanneer Artific ze voor jouw omgeving heeft aangezet. Tot dan antwoordt OS op registreren met 409; de feed werkt wel.