Événements et webhooks¶

Vos propres programmes peuvent suivre ce qui change dans OS sans redemander sans cesse toutes les listes. Chaque modification des personnes, des paramètres ou du service de votre organisation est enregistrée comme un événement. Votre programme lit ces événements dans le flux, ou les reçoit sous la forme d'un webhook signé, à une adresse que vous avez enregistrée.

Un événement n'est pas une notification. Une notification est une nouvelle pour des personnes, dans leur langue. Un événement est une référence à quelque chose qui a changé, destinée à un programme.

Ce que contient un événement¶

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

• Des références, pas du contenu. refs contient des identifiants, des statuts et les noms des champs modifiés. Jamais un nom, une adresse e-mail, un montant ni rien de ce que quelqu'un a écrit. Si votre programme veut en savoir plus, il demande l'élément lui-même à OS, et OS décide alors de nouveau ce qu'il peut voir.
• Le curseur est un nombre écrit sous forme de texte, numéroté en continu par organisation, dans l'ordre où OS a enregistré les événements.
• L'ordre. Deux modifications très rapprochées peuvent être enregistrées dans l'un ou l'autre ordre, et les webhooks peuvent arriver dans n'importe quel ordre. Triez sur cursor, et relisez l'élément quand son état actuel compte.

Les types d'événements qui existent figurent dans Événements.

Le flux ou un webhook¶

OS conserve les événements sept jours. Si vous demandez le flux avec un curseur dont les événements suivants ont déjà disparu, OS répond 410 : relisez alors l'état et repartez sans curseur.

Qui voit quoi¶

Un webhook agit au nom d'un compte de votre organisation, en général un compte de service, et jamais au nom de la personne qui l'a enregistré. À chaque livraison, OS décide de nouveau si ce compte peut voir l'événement : il doit avoir see sur event, et see sur l'élément dont parle l'événement. Si le compte ne voit pas un membre, le webhook ne reçoit pas non plus les événements concernant ce membre. Une telle livraison figure dans le journal comme ignorée, pour que vous puissiez voir pourquoi elle n'est pas arrivée.

Qui lit le flux ne voit de la même manière que les événements qu'il peut voir.

Seul peut enregistrer un webhook qui a write sur webhook, peut modifier le compte et a lui-même tout ce que ce compte a. Un administrateur (org-admin) l'a.

Quand une adresse ne répond pas¶

OS réessaie une livraison échouée après environ 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures, 12 heures et 24 heures : huit tentatives en presque deux jours. Après cinq échecs de suite, le webhook est dit défaillant : OS envoie alors une livraison à la fois et retient le reste. Dès qu'une réussit, le webhook est de nouveau actif et le reste suit. S'il reste défaillant trois jours, ou si le compte n'est plus actif, il est désactivé. Les administrateurs de votre organisation reçoivent une notification dans les deux cas. Les événements restent dans le flux, et un administrateur peut réactiver le webhook.

Une adresse qui répond 410 dit qu'elle n'existe plus : OS désactive aussitôt le webhook.

Sécurité¶

• Chaque livraison est signée avec le secret du webhook. Vérifiez la signature avant de faire quoi que ce soit du contenu (comment).
• OS n'envoie qu'à des adresses https dont le nom d'hôte est joignable sur internet. Une adresse qui mène à une adresse interne ou privée, OS la refuse, à l'enregistrement et à chaque tentative.
• OS ne suit aucune redirection et ne lit pas la réponse de votre adresse.
• Ne mettez aucun secret dans l'adresse : qui peut voir le webhook voit l'adresse.

Les webhooks ne sont activés que lorsqu'Artific les a activés pour votre environnement. D'ici là, OS répond 409 à l'enregistrement ; le flux fonctionne.