Events & Webhooks

Kaiten emits a domain event for every change to the model and for every decision it makes: a customer created, a grant updated, a usage report accepted or rejected, a flag evaluated. Events are the integration surface — what your CRM, your billing engine, and your own services react to — and the same stream feeds the audit trail. How events reach you depends on the edition; what they are does not.

What an event is

Every event has a name — a past-participle constant such as CUSTOMER_CREATED, LICENSE_ENTITLEMENT_ASSIGNED, INSTANCE_ENTITLEMENT_USAGE_REACHED — and a versioned type such as com.kaiten.customer.v1.created. The payload is the entity or the change the event is about. There are 55 events across 10 domains: customers, instances, licenses, entitlements, feature flags, components, releases, deployment zones, metadata fields, identity. Two families run through them — changes (create, update, delete, assign) and evaluations (ENTITLEMENT_VALUE_GET, FEATURE_FLAG_EVALUATED, the usage-report outcomes) — and every one is listed, with its payload contract, in the event catalog.

Events describe Kaiten's model and Kaiten's decisions. FEATURE_FLAG_EVALUATED carries the flag, the variant, and the reason, and deliberately not the evaluation context — no targeting key, no user attribute leaves your product.

Written with the change

An event is inserted in the same database transaction as the write it describes: the two commit together or not at all, and if downstream is unavailable the event waits rather than disappearing. From there a change-data-capture pipeline publishes it to the stream. Delivery is at least once: a consumer may see an event twice and deduplicates on its id.

Kaiten is its own first consumer. One delivery of the stream is fanned out to several consumers inside the API — the audit trail, and a CRM connector for the organizations that activated one — each recording what it has processed on its own, so a failure in one is retried for that one alone and never replays the other. The audit trail in turn is what each user's notifications are read from. Your consumers, on either path below, are independent of that fan-out.

Two delivery paths

Kaiten Cloud — managed webhooks

Kaiten Cloud

On Kaiten Cloud, where your organization's License includes webhooks, you register webhook endpoints and subscribe each one to the event types it cares about. Kaiten delivers the published contract — { "name", "type", "data" }, with an optional headers object that names the Instance an event concerns — signs every delivery, retries failures, and keeps a history of recent deliveries you can inspect in the console under Integrations → Webhooks → History (OK, Pending, Sending, Fail). Setup, signatures, and retry behavior: webhooks.

Self-hosted — the event stream itself

The Community Edition ships no managed webhook delivery. Your stack runs the broker, so you consume the stream directly: the same 55 events, on the RabbitMQ exchange your stack publishes to. The message you receive is a CloudEvent per event that carries the outbox row rather than the published webhook contract: its type is the event's, and the row holds the event's name and data. Consuming events documents the consumer setup and the message; the receive events page frames both paths.

Where to go next

The quickstart's next step receives a first event on either edition. The audit trail is the same stream, kept.

Exact reference: data model.