Introduction aux événements

Les événements Ormuz sont les signaux publics émis quand un objet métier change d’état, quand un processus atteint une étape notable ou quand un provider externe est normalisé dans le modèle de la plateforme.

Rôle

Un signal métier, pas une commande

Un événement décrit quelque chose qui s’est déjà produit. Il sert à synchroniser vos systèmes, déclencher un processus, auditer une intégration ou relire l’objet concerné via l’API. Il ne remplace pas les endpoints REST de création ou de transition d’un objet.

Utilisez les identifiants fournis dans les événements pour retrouver les objets concernés et dédupliquer leur traitement.

Contrat

Enveloppe commune

Tous les événements livrés par Ormuz utilisent la même enveloppe. Le champ payload varie selon le type, mais les champs de routage et d’idempotence restent stables.

Champ	Type	Description
`id`	string	Identifiant unique de l’événement. Utilisez-le comme clé d’idempotence côté consommateur.
`type`	string	Nom stable du signal métier, par exemple invoice.issued ou company.updated.
`merchant_id`	string	Marchand auquel appartient l’événement.
`company_id`	string \| null	Entreprise principal concerné lorsque l’événement est rattachable à une company.
`occurred_at`	string	Horodatage ISO 8601 UTC du moment où le signal a été émis.
`context`	object	Contexte public de corrélation, avec la source et les identifiants de requête ou de corrélation lorsqu’ils existent.
`payload`	object	Payload public propre au type : objet, snapshot, projection ou résultat métier enrichi selon son contrat.

Nommage

Types d’événements

Les événements plateforme suivent généralement la forme objet.action, par exemple invoice.issued. Les événements issus d’une extension sont préfixés par extension.<extension_key>. pour conserver leur origine technique sans les confondre avec les événements métier Ormuz.

Famille	Exemples
Entreprise	`company.created, company.updated, company.suspended, contact.updated`
Onboarding & conformité	`onboarding_case.completed, onboarding_case.rejected, compliance_check.created, compliance_check.review_required`
Commerce	`order.created, order.confirmed, checkout_session.completed, purchase_order.approved`
Facturation	`invoice.issued, invoice.overdue, receivable.updated, credit_limit.updated`
Paiements	`psp_payment.succeeded, payment.received, payment_allocation.complete`
Orchestration	`process.instance.replayed, process.user_action.completed, approval_request.resolved`
Extensions	`extension.stripe.payment_intent.succeeded, extension.stripe.charge.refunded`

La liste exhaustive est exposée par GET /v1/events et détaillée dans le catalogue des événements.

Consommation

Recevoir et utiliser les événements

Un type d’événement déclare les surfaces auxquelles il peut être livré. Tous les événements plateforme Core sont disponibles pour les webhooks sortants ; la plupart, mais pas tous, sont également proposés comme déclencheurs de processus. Consultez le catalogue pour vérifier la capacité du type choisi.

Canal	Usage
Webhooks sortants	Livrer les événements Ormuz à votre application via HTTP signé.
Déclencheurs de processus	Démarrer ou reprendre un processus quand un événement métier attendu se produit.
Catalogue API	Lister les types disponibles avec GET /v1/events pour configurer vos abonnements.

Pour exposer les événements à votre application, créez un endpoint dans Recevoir des webhooks et abonnez-le aux types dont vous avez besoin.

Fiabilité

Idempotence et ordre de traitement

Un consommateur doit pouvoir recevoir deux fois le même événement sans produire deux effets métier. Persistez l’identifiant id avant d’exécuter un effet irréversible, puis ignorez les événements déjà vus.

Ne supposez pas un ordre global strict entre tous les types d’événements.
Utilisez occurred_at pour comparer des signaux et relisez l’objet courant si l’ordre métier compte.
Interprétez le payload selon le contrat du type : certains sont des snapshots, d’autres des objets ou résultats enrichis.
Préférez une liste explicite dans filter_types lorsque votre endpoint n’a besoin que d’un sous-ensemble d’événements.

Extensions

Événements de extension normalisés

Les webhooks entrants de providers peuvent émettre des événements préfixés extension.. Ces événements conservent la provenance technique et peuvent porter un brouillon d’objet plateforme, mais ils ne créent pas directement l’objet métier final.

La configuration de ces endpoints est décrite dans Webhooks entrants des extensions.

Évolution

Contrats et compatibilité

Les types d’événements sont le contrat principal de filtrage. Les payloads peuvent s’enrichir avec de nouveaux champs publics; les consommateurs doivent ignorer les champs inconnus et se baser sur les champs nécessaires à leur cas d’usage.

Pour comprendre la frontière de compatibilité des contrats publics, consultez le versionnement des contrats publics.