5.1.x deployments interact with FlowX over Kafka in two ways: messages produced by FlowX services (process start, task events, audit, document operations) and messages produced into FlowX by your own integrations. The 5.1 → 5.9 jump introduces one breaking change that affects custom producers, several new topics introduced by new services, and one topic-ownership move that affects Kafka ACLs.Documentation Index
Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
Use this file to discover all available pages before exploring further.
Mandatory Fx-Organization-Id header
On 5.9.x, every FlowX Kafka consumer validates the Fx-Organization-Id header on every incoming message. Messages without this header are rejected immediately and not retried.
This is the single most likely cause of silent breakage post-upgrade for customers who maintain custom Kafka producers (process start, task operations, engine responses, integration callbacks).
What to set
Set the header value to the Organization UUID provided by FlowX during organization registration. The same value you configure as theORGANIZATION_ID environment variable on every FlowX service. See Prerequisites.
Where this applies
| Surface | Behavior in 5.9.0 |
|---|---|
| Kafka topics consumed by FlowX | Header is mandatory. Missing → message rejected, not retried. |
| Kafka responses sent back to FlowX | Preserve all received headers (including Fx-Organization-Id) when responding from your connector. |
| REST API endpoints | Header is read into security context when present, but not enforced in 5.9.0. Enforcement on authenticated REST requests is tracked separately and will land in a later release. |
Affected consumer surfaces
Validation runs on every FlowX Kafka listener. Concretely, custom producers that target the following topic families must add the header:- Process start (
*.core.trigger.start.process.*,*.core.trigger.start-for-event.process.*) - Process operations (
*.core.trigger.operation.*,*.core.trigger.operations.bulk.*): task assign/unassign, hold/unhold, terminate, including bulk - Connector responses (
*.engine.receive.*) - Webhook ingestion, document plugin triggers, integration sync topics
New Kafka topics that did not exist in 5.1.x
The 5.1 → 5.9 jump adds new microservices (organization-manager, webhook-gateway, license) and new features (Knowledge Base, Multi-file Upload, UI Flow session variables, Email Trigger). Each brings its own topics. For the complete list with producer/consumer mapping, see the deployment guidelines linked at the bottom of this page.
The high-level groups your platform/SRE team should be aware of:
| Theme | Notable topics |
|---|---|
organization-manager + Document plugin enhancements | ai.flowx.organization.events.v1, ai.flowx.application-version.resources-usages.*, ai.flowx.plugin.document.trigger.persist.document.*, ai.flowx.build.runtime-data.v1 |
webhook-gateway + UI Flow session variables | ai.flowx.core.trigger.start-for-event.process.v1, ai.flowx.core.trigger.ui-flow.update.v1, ai.flowx.plugin.document.trigger.persist.document.session.v1 |
| AI Providers UI (LLM config) | ai.flowx.llm.config.changed.v1 |
license service + KB internal Kafka path + bulk document persistence | ai.flowx.license.events.v1, ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1 / -response.v1, ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1 |
If you manage Kafka topic creation manually (rather than letting FlowX auto-create), pre-create the topics listed in each release’s deployment guidelines before deploying the corresponding service versions.
New producer on WorkspaceCreatedEvent: organization-manager
organization-manager now publishes WorkspaceCreatedEvent as part of the organization-provisioning flow. authorization-system continues to publish the event on regular workspace creation, so on 5.9.x the topic has two producers, not one.
If you manage Kafka ACLs at the topic level, grant producer access to both services:
authorization-system. Publishes on user-driven workspace create (unchanged from 5.1.x).organization-manager. Publishes during org provisioning (new in 5.9.x).
Knowledge Base indexer ↔ embedder moves to Kafka
On 5.9.x, the Knowledge Base indexer → embedder path uses a Kafka request/response pair instead of synchronous gRPC:ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1(indexer producer, embedder consumer)ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1(embedder producer, indexer consumer)
Custom-producer audit checklist
Before the upgrade window, walk through every Kafka integration that produces into FlowX:Inventory
List every system that publishes to a FlowX Kafka topic. Common sources: backends that start processes by name, task-management automations, connector implementations that respond to engine requests, scheduled jobs that emit events.
Add `Fx-Organization-Id` to producer code
For each producer, add the header before sending. The value is your Organization UUID (same as the
ORGANIZATION_ID env var).Preserve headers on Kafka responses
Connectors that respond to FlowX engine requests must copy all received Kafka headers (including
Fx-Organization-Id, Fx-Workspace-Id, fxContext, Fx-AppId) into the response. The simplest pattern: originalHeaders.forEach(producerRecord.headers()::add).Verify in staging
Run end-to-end with a 5.9.x staging environment before production. The failure mode is non-retryable rejection: messages are dropped, not queued for retry, so the breakage stays silent unless you read the consumer logs.
Related resources
Creating a Kafka producer
Full reference for required Kafka headers on the 5.9.x baseline, including the
Fx-Organization-Id, Fx-Workspace-Id, and jwt headers.Finding identifiers and parameters
Where to find the Organization UUID, workspace ID, project ID, and other identifiers required in Kafka and REST integrations.
v5.9.0 deployment guidelines
Component versions, Kafka topic ownership, and env vars for the 5.9.x baseline.
Prerequisites
Get your Organization UUID and complete the pre-upgrade inventory before working through this page.