Events and webhooks¶

Your own programs can follow what changes in OS without asking for every list again and again. Each change to your organisation's people, settings or service is recorded as an event. Your program reads those events from the feed, or receives them as a signed webhook at an address you registered.

An event is not a notification. A notification is news for people, in their language. An event is a reference to something that changed, meant for a program.

What an event holds¶

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

• References, not content. refs holds ids, statuses and the names of changed fields. Never a name, an e-mail address, an amount or anything someone wrote. When your program needs more, it asks OS for the thing itself, and OS decides again what it may see.
• The cursor is a number as text, counted per organisation without gaps in the order OS recorded the events.
• Order. Two changes made a moment apart can be recorded in either order, and webhooks can arrive in any order. Sort by cursor, and read the thing when its current state matters.

Which kinds of event there are is in Events.

The feed or a webhook¶

OS keeps events for seven days. If you ask the feed with a cursor whose following events are already gone, OS answers 410: read the current state again and start without a cursor.

Who sees what¶

A webhook acts as an account of your organisation, usually a service account, and never as the person who registered it. At every delivery OS decides again whether that account may see the event: it needs see on event, and see on the thing the event is about. If the account cannot see a member, the webhook does not get the events about that member either. Such a delivery shows in the log as skipped, so you can see why it did not arrive.

Whoever reads the feed likewise sees only the events they may see.

Only someone with write on webhook, who may change the account and holds everything that account holds, can register a webhook. An administrator (org-admin) can.

When an address does not answer¶

OS tries a failed delivery again after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours: eight attempts in almost two days. After five failures in a row the webhook is failing: OS then sends one delivery at a time and holds the rest. When one succeeds again, the webhook is active again and the rest follow. When it has been failing for three days, or its account is no longer active, it is disabled. Your organisation's administrators get a notification each time. The events stay in the feed, and an administrator can enable the webhook again.

An address that answers 410 says it is gone: OS disables the webhook at once.

Security¶

• Every delivery is signed with the webhook's secret. Check the signature before you act on the content (how).
• OS sends only to https addresses with a host name that leads to the internet. An address that leads to an internal or private address is refused, when you register it and at every attempt.
• OS follows no redirect and does not read your address's answer.
• Do not put a secret in the address: whoever may see the webhook sees the address.

Webhooks are on only once Artific has switched them on for your environment. Until then OS answers registering with 409; the feed works.