> ## 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.

# FlowX Events Gateway setup

> This guide will walk you through the process of setting up the events-gateway service.

## Infrastructure prerequisites

Before proceeding with the setup, ensure that the following components have been set up:

* **Redis**
* **Kafka**

***

## Configuration

### Configuring Kafka

Set the following Kafka-related configurations using environment variables:

| Configuration Parameter            | Default Value    | Description                                                              |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------ |
| `KAFKA_BOOTSTRAP_SERVERS`          | `localhost:9092` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`)      |
| `KAFKA_SECURITY_PROTOCOL`          | `PLAINTEXT`      | Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) |
| `KAFKA_MESSAGE_MAX_BYTES`          | `52428800`       | Maximum message size in bytes (50 MB)                                    |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | `10`             | Retry interval for auth exceptions (seconds)                             |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

#### Topic naming configuration

| Configuration Parameter          | Default Value | Description                         |
| -------------------------------- | ------------- | ----------------------------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | `ai.flowx.`   | Package prefix for topic names      |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | ` `           | Environment segment for topic names |
| `KAFKA_TOPIC_NAMING_VERSION`     | `.v1`         | Version suffix for topic names      |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | `.`           | Primary separator for topic names   |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | `-`           | Secondary separator for topic names |

#### Group IDs

The configuration parameters "KAFKA\_CONSUMER\_GROUPID\_\*" are used to set the consumer group name for Kafka consumers that consume messages from topics. Consumer groups in Kafka allow for parallel message processing by distributing the workload among multiple consumer instances. By configuring the consumer group ID, you can specify the logical grouping of consumers that work together to process messages from the same topic, enabling scalable and fault-tolerant message consumption in your Kafka application.

| Configuration Parameter                                   | Default value                     | Description                                                          |
| --------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------- |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_MESSAGE`    | `engine-commands-message`         | Consumer group ID for processing engine commands messages            |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_DISCONNECT` | `engine-commands-disconnect`      | Consumer group ID for processing engine commands disconnect messages |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_CONNECT`    | `engine-commands-connect`         | Consumer group ID for processing engine commands connect messages    |
| `KAFKA_CONSUMER_GROUPID_TASKCOMMANDS_MESSAGE`             | `task-commands-message`           | Consumer group ID for processing task commands messages              |
| `KAFKA_CONSUMER_GROUPID_PROCESSCOMMANDS_MESSAGE`          | `process-commands-message`        | Consumer group ID for processing process commands messages           |
| `KAFKA_CONSUMER_GROUPID_GENERICCOMMANDS`                  | `generic-commands-message`        | Consumer group ID for processing generic commands messages           |
| `KAFKA_CONSUMER_GROUPID_USERBROADCASTCOMMANDS`            | `user-broadcast-commands-message` | Consumer group ID for processing user broadcast commands messages    |

#### Threads

The configuration parameters "KAFKA\_CONSUMER\_THREADS\_\*" are utilized to specify the number of threads assigned to Kafka consumers for processing messages from topics. These parameters allow you to fine-tune the concurrency and parallelism of your Kafka consumer application, enabling efficient and scalable message consumption from Kafka topics.

| Configuration Parameter                                   | Default value | Description                                                          |
| --------------------------------------------------------- | ------------- | -------------------------------------------------------------------- |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_MESSAGE`    | `10`          | Number of threads for processing engine commands messages            |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_DISCONNECT` | `5`           | Number of threads for processing engine commands disconnect messages |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_CONNECT`    | `5`           | Number of threads for processing engine commands connect messages    |
| `KAFKA_CONSUMER_THREADS_TASKCOMMANDS`                     | `10`          | Number of threads for task commands messages                         |
| `KAFKA_CONSUMER_THREADS_PROCESSCOMMANDS`                  | `10`          | Number of threads for processing process commands messages           |
| `KAFKA_CONSUMER_THREADS_GENERICCOMMANDS`                  | `10`          | Number of threads for processing generic commands messages           |
| `KAFKA_CONSUMER_THREADS_USERBROADCASTCOMMANDS`            | `10`          | Number of threads for processing user broadcast commands messages    |

#### Events Gateway pattern

| Configuration Parameter             | Default value                      | Description                              |
| ----------------------------------- | ---------------------------------- | ---------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_PATTERN` | `ai.flowx.eventsgateway.receive.*` | Pattern for Events Gateway communication |

#### Kafka topics related to process instances

| Configuration Parameter                                   | Default value                                          | Description                                   |
| --------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_MESSAGE`    | `ai.flowx.eventsgateway.engine.commands.message.v1`    | Topic for engine commands messages            |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_DISCONNECT` | `ai.flowx.eventsgateway.engine.commands.disconnect.v1` | Topic for engine commands disconnect messages |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_CONNECT`    | `ai.flowx.eventsgateway.engine.commands.connect.v1`    | Topic for engine commands connect messages    |

#### Kafka topics related to process commands

| Configuration Parameter                        | Default value                                        | Description                         |
| ---------------------------------------------- | ---------------------------------------------------- | ----------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESS_IN_MESSAGE` | `ai.flowx.eventsgateway.process.commands.message.v1` | Topic for process commands messages |

#### Kafka topics related to user messages

| Configuration Parameter                             | Default value                                 | Description                          |
| --------------------------------------------------- | --------------------------------------------- | ------------------------------------ |
| `KAFKA_TOPIC_EVENTSGATEWAY_USERMESSAGES_IN_MESSAGE` | `ai.flowx.core.designer.notification.user.v1` | Topic for user notification messages |

### Configuring authorization & access roles

Events Gateway validates incoming tokens with the JWT public key mechanism:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                          |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                                             | Token validation mechanism (JWT public key validation)                                                                                                | `jwt-public-key`                       |
| `SECURITY_OAUTH2_BASESERVERURL`                                             | Base URL of the Keycloak server                                                                                                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                                   | Service-accounts realm ID                                                                                                                             | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`                   | URL of the organization-manager service, used by the security library                                                                                 | `http://organization-manager:80`       |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                        |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

### Service communication

| Environment Variable        | Description                             | Default Value             |
| --------------------------- | --------------------------------------- | ------------------------- |
| `FLOWX_URLS_RUNTIMEMANAGER` | Base URL of the Runtime Manager service | `http://runtime-manager/` |

### Redis configuration

FlowX Events Gateway uses Redis for real-time message distribution. The process engine sends messages to the events-gateway, which is responsible for sending them to Redis.

Events Gateway supports all Redis deployment modes (Standalone, Sentinel, and Cluster). For detailed Redis configuration including all deployment modes and parameters, see the [Redis Configuration](/5.9/setup-guides/redis-configuration) guide.

#### Quick reference

Common Redis configuration parameters:

| Configuration Parameter             | Description                             | Example Value             |
| ----------------------------------- | --------------------------------------- | ------------------------- |
| `SPRING_DATA_REDIS_HOST`            | Redis server hostname (Standalone mode) | `localhost`               |
| `SPRING_DATA_REDIS_PORT`            | Redis server port (Standalone mode)     | `6379`                    |
| `SPRING_DATA_REDIS_PASSWORD`        | Redis authentication password           | `yourpassword`            |
| `SPRING_DATA_REDIS_SENTINEL_MASTER` | Sentinel master name (Sentinel mode)    | `mymaster`                |
| `SPRING_DATA_REDIS_SENTINEL_NODES`  | Sentinel nodes (Sentinel mode)          | `host1:26379,host2:26379` |
| `SPRING_DATA_REDIS_CLUSTER_NODES`   | Cluster nodes (Cluster mode)            | `host1:6379,host2:6379`   |

<Info>
  For complete Redis configuration details including Sentinel mode, Cluster mode, SSL/TLS setup, and troubleshooting, refer to the [Redis Configuration guide](/5.9/setup-guides/redis-configuration).
</Info>

### Events

This configuration helps manage how event data is stored and accessed in Redis.

| Configuration Parameter        | Default | Description                                                                                           |
| ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `EVENTS_REDIS_FREQUENCYMILLIS` | 300     | Time interval (in milliseconds) between Redis queries by the events gateway to check for new messages |
| `EVENTS_REDIS_TTLHOURS`        | 4       | Sets the time-to-live for events in Redis to 4 hours                                                  |

### SSE cleanup configuration

Configure how Server-Sent Events (SSE) connections are cleaned up:

| Configuration Parameter           | Default | Description                                                         |
| --------------------------------- | ------- | ------------------------------------------------------------------- |
| `EVENTS_SSE_CLEANUP_INTERVALMINS` | `5`     | Interval in minutes between SSE connection cleanup cycles           |
| `EVENTS_SSE_CLEANUP_MAXAGEMINS`   | `10`    | Maximum age in minutes before an inactive SSE connection is removed |

### Configuring logging

The following environment variables control log levels:

| Configuration Parameter | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `LOGGING_LEVEL_ROOT`    | Logging level for the root Spring Boot microservice logs |
| `LOGGING_LEVEL_APP`     | Logging level for the application-level logs             |

***

## Ingress and CORS

The Events Gateway is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. The path is preserved end-to-end (no rewrite), because Server-Sent Events use the same path on the backend as on the client.

### Service routes

| Host group | External path | Backend receives  | Notes          |
| ---------- | ------------- | ----------------- | -------------- |
| admin      | `/api/events` | `/api/events/...` | Path preserved |
| public     | `/api/events` | `/api/events/...` | Path preserved |

Paths are set through `services.events-gateway.ingress.admin.path` / `services.events-gateway.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values. No rewrite is applied because Events Gateway expects the same path on the backend.

<Note>
  Server-Sent Events are long-lived HTTP connections. If you front Events Gateway with a custom ingress controller or reverse proxy, set generous read timeouts (300s+) and disable response buffering on the SSE path.
</Note>

### CORS configuration

| Environment Variable            | Description                                                                                                                                                                                   | Default Value |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOW_ORIGIN` | Comma-separated list of origins allowed to open SSE connections from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that subscribes to events. | `-`           |

Allowed methods, allowed headers, and credential handling are baked into the service's `application.yaml` with safe defaults for SSE traffic. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="SSE connections dropping unexpectedly">
    **Symptoms:** Clients lose real-time updates intermittently, SSE connections close after a timeout period.

    **Solutions:**

    1. Check your ingress timeout settings — SSE connections require longer timeouts than standard HTTP requests. Set `proxy-read-timeout` and `proxy-send-timeout` to at least `3600` seconds
    2. Verify keep-alive configuration on your load balancer and ingress controller
    3. Review the `EVENTS_SSE_CLEANUP_MAXAGEMINS` setting — ensure it is not set too low for your use case
    4. Check for network proxies or firewalls that may terminate long-lived connections
  </Accordion>

  <Accordion title="Events not reaching the UI">
    **Symptoms:** Process updates do not appear in the Designer or end-user interface, despite successful process execution.

    **Solutions:**

    1. Verify Kafka consumer configuration — check that the consumer group IDs match expected values
    2. Confirm that the `KAFKA_TOPIC_EVENTSGATEWAY_PATTERN` matches the topics being published to by the process engine
    3. Check Kafka consumer lag using your monitoring tools to identify backpressure issues
    4. Ensure the events-gateway service has network access to Kafka brokers
  </Accordion>

  <Accordion title="High latency on events">
    **Symptoms:** Noticeable delay between process execution and UI updates.

    **Solutions:**

    1. Check the Redis connection — verify `SPRING_DATA_REDIS_HOST` and `SPRING_DATA_REDIS_PORT` are correct and the Redis instance is responsive
    2. Review `EVENTS_REDIS_FREQUENCYMILLIS` — lower values reduce latency but increase Redis load
    3. Check Kafka partition configuration — ensure sufficient partitions for your consumer thread count
    4. Monitor Kafka consumer thread counts (`KAFKA_CONSUMER_THREADS_*`) and increase if threads are saturated
  </Accordion>

  <Accordion title="WebSocket connection failures">
    **Symptoms:** Browser console shows WebSocket or SSE connection errors, CORS-related error messages.

    **Solutions:**

    1. Verify CORS settings in your ingress configuration allow the Designer and application domains
    2. Ensure the ingress controller supports WebSocket upgrades and SSE connections
    3. Check that the ingress path pattern `/api/events(/|$)(.*)(/|$)(.*)` is correctly configured
    4. Confirm that the `events-gateway` service is reachable from the ingress controller
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Ingress Configuration" icon="globe" href="./ingress-configuration">
    Configure routing, CORS, and SSE-specific ingress settings
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="FlowX Engine Setup" icon="engine" href="./flowx-engine-setup-guide/engine-setup">
    Configure the process engine that publishes events to the gateway
  </Card>
</CardGroup>