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

Set the following environment variables to connect to the identity management platform:

| Environment Variable                   | Description                           | Default Value |
| -------------------------------------- | ------------------------------------- | ------------- |
| `SECURITY_TYPE`                        | Security type                         | `oauth2`      |
| `SECURITY_OAUTH2_BASESERVERURL`        | Base URL of the OAuth2 server         |               |
| `SECURITY_OAUTH2_REALM`                | OAuth2 realm name                     |               |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID`     | Client ID for token introspection     |               |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | Client secret for token introspection |               |

### 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.1/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.1/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_MODE`            | polling | How the events gateway reads real-time events from Redis. `polling` checks for new events at the `EVENTS_REDIS_FREQUENCYMILLIS` interval; `blocking` holds a Redis connection open per read. Defaults to `polling` starting with 5.1.10 for Redis connection stability |
| `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

<Info>
  **New in v5.5.0**
</Info>

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 configuration

The Events Gateway service uses a specialized ingress configuration for Server-Sent Events (SSE). For complete setup instructions, see the [Ingress Configuration Guide](./ingress-configuration#events-gateway-exception).

**Service-specific values for Events Gateway:**

* **Ingress name:** `events-gateway-admin`
* **Service path:** `/api/events(/|$)(.*)(/|$)(.*)`
* **Service name:** `events-gateway`
* **Rewrite target:** `/api/events/$2`
* **Fx-Workspace-Id:** Not required (SSE exception)

<Note>
  Events Gateway does not require the `Fx-Workspace-Id` header because it handles real-time SSE connections with different security requirements. See the [Events Gateway exception](./ingress-configuration#events-gateway-exception) for details.
</Note>

<Card title="Complete Ingress Configuration" href="./ingress-configuration#events-gateway-exception" icon="network-wired">
  View the Events Gateway-specific ingress pattern in the centralized guide.
</Card>

***

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


## Related topics

- [FlowX Designer setup](/5.1/setup-guides/designer-setup-guide.md)
- [FlowX.AI Events Gateway](/5.1/docs/platform-deep-dive/core-components/events-gateway.md)
- [FlowX Admin setup](/5.1/setup-guides/admin-setup-guide.md)
- [FlowX Engine setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup.md)
- [FlowX CMS setup](/5.1/setup-guides/cms-setup.md)