Introduction to events
Ormuz events are public signals emitted when a business object changes state, a process reaches a notable step, or an external provider signal is normalized into the platform model.
Role
A business signal, not a command
An event describes something that already happened. It can synchronize your systems, trigger a process, audit an integration, or let you reread the relevant object through the API. It does not replace REST endpoints for creating or transitioning an object.
Use identifiers supplied in events to retrieve relevant objects and deduplicate processing.
Contract
Enveloppe commune
All events delivered by Ormuz use the same envelope. The field
payload varies by type, but routing and idempotency fields remain stable.
| Field | Type | Description |
|---|---|---|
id | string | Unique event identifier. Use it as the consumer-side idempotency key. |
type | string | Stable business-signal name, for example `invoice.issued` or `company.updated`. |
merchant_id | string | Merchant to which the event belongs. |
company_id | string | null | Primary company concerned when the event can be attached to a company. |
occurred_at | string | ISO 8601 UTC timestamp when the signal was emitted. |
context | object | Public correlation context, with source and request/correlation identifiers when available. |
payload | object | Public payload specific to the type: object, snapshot, projection, or enriched business result according to its contract. |
Naming
Event types
Platform events generally follow the form objet.action,
for example invoice.issued. Events originating from an extension are prefixed with extension.<extension_key>. to preserve their technical origin without confusing them with Ormuz business events.
| Family | Examples |
|---|---|
| Company | company.created, company.updated, company.suspended, contact.updated |
| Onboarding & compliance | onboarding_case.completed, onboarding_case.rejected, compliance_check.created, compliance_check.review_required |
| Commerce | order.created, order.confirmed, checkout_session.completed, purchase_order.approved |
| Invoicing | invoice.issued, invoice.overdue, receivable.updated, credit_limit.updated |
| Payments | 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 |
The exhaustive list is exposed by GET /v1/events and detailed in the
event catalog.
Consumption
Receive and use events
An event type declares the surfaces to which it can be delivered. All Core platform events are available for outbound webhooks; most, but not all, are also offered as process triggers. Check the catalog for the capability of the selected type.
| Canal | Usage |
|---|---|
| Webhooks sortants | Deliver Ormuz events to your application through signed HTTP. |
| Process triggers | Start or resume a process when an expected business event occurs. |
| Catalogue API | List available types with GET /v1/events to configure your subscriptions. |
To expose events to your application, create an endpoint in Receive webhooks and subscribe it to the types you need.
Reliability
Idempotency and processing order
A consumer must be able to receive the same event twice without producing two business effects. Persist the identifier id before executing an irreversible effect, then ignore events already seen.
- Do not assume strict global ordering across all event types.
- Use
occurred_atto compare signals and reread the current object when business ordering matters. - Interpret the
payloadaccording to the type contract: some are snapshots, others objects or enriched results. - Prefer an explicit list in
filter_typeswhen your endpoint needs only a subset of events.
Extensions
Normalized extension events
Inbound provider webhooks may emit events prefixed with
extension.. These events preserve technical provenance and may carry a platform-object draft, but they do not directly create the final business object.
Configuration of these endpoints is described in Inbound extension webhooks.
Evolution
Contracts and compatibility
Event types are the primary filtering contract. Payloads may be enriched with new public fields; consumers should ignore unknown fields and rely on the fields required by their use case.
To understand the compatibility boundary of public contracts, see public contract versioning.