Events & integration¶
How other systems find out that something happened in Cortex, and just as importantly, the honest limits of what is exposed today.
The internal event model¶
Cortex has a canonical domain-event catalogue: past-tense facts like JournalPosted,
SupplierInvoiceApproved, PaymentSettled. Events are published through a transactional outbox
onto an event backbone, each wrapped in a standard envelope:
| Envelope field | Purpose |
|---|---|
messageId |
Unique id for this event (consumers dedupe on it). |
idempotencyKey |
The business key that produced it. |
correlationId / causationId |
Trace and cause chains. |
tenantId |
The owning institution. |
occurredAt |
Business time of the event. |
schemaVersion |
For safe evolution. |
Delivery is at-least-once: consumers must dedupe on messageId.
Real vs aspirational: read this before you design around events
The event model is real, but in current builds much of it runs in-process, not on a live broker. Without a configured message backbone the integration-event publisher defaults to a no-op / logging transport, and ERP integration events are delivered in-process via application events. A live external broker is still an open deployment dependency. Do not build a third-party integration that assumes it can subscribe to a running Kafka topic today. Confirm the backbone is provisioned for your deployment first.
There is no generic webhook egress¶
Cortex does not expose a general "subscribe to domain events" webhook feed for third parties. If you are integrating an external system, plan around these facts:
- Outbound effects go through per-rail adapters, not an event feed. A payment leaves as an ISO 20022 or ISO 8583 message to its rail. The platform speaks the rail's protocol, it does not emit a generic event you subscribe to.
- "Webhooks" here are inbound. The webhook/callback endpoints are ingress: where third-party rails and billers post status callbacks (accepted, settled, returned) back to Cortex, which maps them onto the owning payment's state machine.
How to integrate today¶
Given the above, the reliable integration patterns are:
- Call the REST API for reads and writes (this is the primary, supported surface).
- Poll the relevant list endpoints with
from/to/statusfilters for state you need to react to. - For payments, receive rail callbacks at the inbound webhook ingress if you are the rail side.
- If you own the deployment and have provisioned a broker, consume the outbox topics directly, but treat that as a deployment-coupled integration, not a public contract.
If you need event-driven integration and are unsure whether the backbone is live in your environment, ask your platform administrator rather than assuming.