Webhook Gateway setup

Dependencies

Before setting up the Webhook Gateway, ensure you have the following dependencies in place:

PostgreSQL database for storing webhook registration data
Kafka for publishing process start events
Keycloak (or compatible OAuth2 provider) for authentication and authorization
SpiceDB for fine-grained authorization

Infrastructure prerequisites

Component	Description
PostgreSQL	Dedicated database named `webhook_gateway`
Kafka	Message broker for triggering process starts
Keycloak	Identity provider for service authentication
SpiceDB	Authorization service for workspace validation

Configuration

Authorization configuration

The Webhook Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the mainIdentity client registration) in the service-accounts realm:

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`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`	Service account client ID	`flowx-webhook-gateway-sa`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`	Service account client secret (Keycloak-issued)
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`	Anonymous service account client ID, used for anonymous runtime access	`flowx-anonymous-sa`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET`	Anonymous service account client secret
`SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`	Provider token URI, resolved against the service-accounts realm	`${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token`

Upgrading from 5.1.x? Remove the legacy opaque-token env vars: SECURITY_OAUTH2_REALM, SECURITY_OAUTH2_CLIENT_CLIENTID, SECURITY_OAUTH2_CLIENT_CLIENTSECRET, and SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the authentication and IAM migration guide for the full list.

The Webhook Gateway exposes /webhooks/** as public (unauthenticated) paths for receiving incoming webhooks. The /api/** paths require a valid JWT token.

PostgreSQL configuration

The Webhook Gateway uses its own dedicated PostgreSQL database for storing webhook registration data.

Environment Variable	Description	Default Value
`SPRING_DATASOURCE_URL`	JDBC connection URL for PostgreSQL	`jdbc:postgresql://postgresql:5432/webhook_gateway`
`SPRING_DATASOURCE_USERNAME`	Database username	`flowx`
`SPRING_DATASOURCE_PASSWORD`	Database password	-

Ensure the webhook_gateway database is created before deploying the service. The Webhook Gateway will manage its own schema migrations via Liquibase.

Kafka configuration

The Webhook Gateway is a producer-only service — it publishes messages to Kafka but does not consume from any topics. It publishes to two topics: one for starting new processes and one for resuming waiting process instances.

Core Kafka settings

Environment Variable	Description	Default Value
`SPRING_KAFKA_BOOTSTRAP_SERVERS`	Address of the Kafka server(s)	`localhost:9092`
`SPRING_KAFKA_SECURITY_PROTOCOL`	Security protocol for Kafka connections	`PLAINTEXT`
`KAFKA_AUTHEXCEPTIONRETRYINTERVAL`	Retry interval after authorization exceptions (seconds)	`10`

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`

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.

Topic naming configuration

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

Kafka topics

The Webhook Gateway publishes to the following Kafka topics:

Environment Variable	Description	Default Value
`KAFKA_TOPIC_PROCESS_START_OUT`	Topic for triggering process starts from webhook events (Message Start Event)	`ai.flowx.core.trigger.start-for-event.process.v1`
`KAFKA_TOPIC_PROCESS_EVENT_MESSAGE`	Topic for resuming running process instances from webhook events (Message Catch Intermediate Event)	`ai.flowx.core.message.event.process.v1`

CAS lib configuration (SpiceDB)

Environment Variable	Description	Default Value
`FLOWX_SPICEDB_HOST`	SpiceDB hostname	`spicedb`
`FLOWX_SPICEDB_PORT`	SpiceDB gRPC port	`50051`
`FLOWX_SPICEDB_TOKEN`	SpiceDB authentication token	-
`FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION`	Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX.	`CUSTOM`

Service communication

The Webhook Gateway communicates with the following FlowX services:

Environment Variable	Description	Default Value
`FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`	Organization Manager base URL	`http://organization-manager:80`
`FLOWX_LIB_CASCLIENT_SERVICES_AUTHORIZATIONSYSTEM_BASEURL`	Authorization System base URL	`http://authorization-system:80`

Logging configuration

Environment Variable	Description	Default Value
`LOGGING_LEVEL_ROOT`	Root logging level	`INFO`
`LOGGING_LEVEL_APP`	Application-specific log level	`INFO`

Secrets management

The Webhook Gateway requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

Secret Name	Description
`SPRING_DATASOURCE_PASSWORD`	PostgreSQL database password
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`	Keycloak service account secret
`FLOWX_SPICEDB_TOKEN`	SpiceDB authentication token
`KAFKA_OAUTH_CLIENT_SECRET`	Kafka OAuth client secret (if using OAuth)

Deployment

Helm values example

Below is an example Helm values configuration for deploying the Webhook Gateway:

fullnameOverride: webhook-gateway

image:
  repository: <your-registry>/webhook-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/webhook_gateway
  SPRING_DATASOURCE_USERNAME: flowx

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # OAuth2
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakWebhookGatewayClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: true
  admin:
    enabled: true
    path: /webhooks

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/routing-name: "webhook-gateway"
  flowx.ai/prometheus-scrape: "webhook-gateway"

Unlike most FlowX services, the Webhook Gateway requires ingress to be enabled because it receives incoming HTTP requests from external systems on the /webhooks path.

Network policies

The Webhook Gateway requires network access to the following services:

Service	Purpose	Pod Label
Kafka	Message broker communication	`flowx.ai/egress-s-kafka`
PostgreSQL	Webhook registration storage	`flowx.ai/egress-s-postgresql`
Keycloak	Authentication	`flowx.ai/egress-s-keycloak`
SpiceDB	Authorization	`flowx.ai/egress-s-spicedb`
Organization Manager	Organization context resolution	`flowx.ai/egress-s-organization-manager`
Authorization System	Access control	`flowx.ai/egress-s-authorization-system`

Monitoring

The Webhook Gateway exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:

podLabels:
  flowx.ai/prometheus-scrape: "webhook-gateway"

Health endpoints

Endpoint	Description
`/actuator/health`	Health check endpoint
`/actuator/metrics`	Prometheus metrics endpoint
`/actuator/info`	App info endpoint

Verify your setup

The Webhook Gateway pod is running and healthy: kubectl get pods -l app=webhook-gateway

The health endpoint returns HTTP 200: curl http://webhook-gateway:8080/actuator/health

Database migrations completed successfully — check pod logs for Liquibase: Update has been successful

SpiceDB connection is established — check pod logs for successful CAS client initialization

The /webhooks ingress path is accessible from external systems

Ingress and CORS

The Webhook Gateway is exposed externally on the admin host. 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 the webhook endpoint URL is the same on the backend as on the client.

Service route

Host group	External path	Backend receives	Notes
admin	`/webhooks`	`/webhooks/...`	Path preserved

The path is set through services.webhook-gateway.ingress.admin.path (or services.webhook-gateway.gateway.admin.paths) in the chart values. No rewrite is applied — webhook URLs your upstream systems POST to must match the path exactly.

CORS configuration

Environment Variable	Description	Default Value
`APPLICATION_CORS_ALLOWORIGIN`	Comma-separated list of origins allowed to call this service from the browser. Most webhook traffic is server-to-server and unaffected; set this only if a Designer or integration UI calls the Webhook Gateway from the browser.	`-`

Allowed methods, allowed headers, and credential handling are baked into the service’s application.yaml with safe defaults. 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.

Troubleshooting

Database connection failures

Symptoms: Service fails to start with database connection errors.Solutions:

Verify the webhook_gateway database exists in PostgreSQL
Check that the database user has appropriate permissions
Ensure network connectivity between the pod and PostgreSQL service
Verify the JDBC URL format is correct

SpiceDB connection failures

Symptoms: Authorization errors or service fails to initialize CAS client.Solutions:

Verify SpiceDB is running and reachable at the configured host and port
Check that the SpiceDB token is correct
Ensure network policies allow gRPC traffic to SpiceDB on port 50051
Review pod logs for specific CAS client error messages

Kafka publishing failures

Symptoms: Webhook events not triggering process starts.Solutions:

Verify Kafka bootstrap servers are reachable
Check that the ai.flowx.core.trigger.start-for-event.process.v1 topic exists
Ensure the service has producer permissions on the topic
Review pod logs for Kafka producer errors

Webhook endpoint not reachable

Symptoms: External systems cannot reach the webhook URL.Solutions:

Verify ingress is enabled and the /webhooks path is configured
Check that network policies allow inbound traffic to the Webhook Gateway
Ensure DNS resolves correctly for the webhook URL
Verify the service is listening on port 8080

Service account authentication errors

Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:

Verify the Keycloak service account is properly configured
Check that client secrets match between configuration and Keycloak
Ensure the service account has required roles assigned
Verify SECURITY_TYPE is set to jwt-public-key

SpiceDB Configuration

Fine-grained authorization setup

Kafka Authentication

Configure Kafka security and authentication

IAM Configuration

Identity and access management setup

Microservices

AI Platform

Plugins

Observability

Access management

Webhook Gateway setup

Dependencies

Infrastructure prerequisites

Configuration

Authorization configuration

PostgreSQL configuration

Kafka configuration

Core Kafka settings

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Kafka topics

CAS lib configuration (SpiceDB)

Service communication

Logging configuration

Secrets management

Deployment

Helm values example

Network policies

Monitoring

Health endpoints

Verify your setup

Ingress and CORS

Service route

CORS configuration

Troubleshooting

SpiceDB Configuration

Kafka Authentication

IAM Configuration

​Dependencies

​Infrastructure prerequisites

​Configuration

​Authorization configuration

​PostgreSQL configuration

​Kafka configuration

​Core Kafka settings

​OAuth authentication (when using SASL_PLAINTEXT)

​Topic naming configuration

​Kafka topics

​CAS lib configuration (SpiceDB)

​Service communication

​Logging configuration

​Secrets management

​Deployment

​Helm values example

​Network policies

​Monitoring

​Health endpoints

​Verify your setup

​Ingress and CORS

​Service route

​CORS configuration

​Troubleshooting

​Related resources

SpiceDB Configuration

Kafka Authentication

IAM Configuration

Dependencies

Infrastructure prerequisites

Configuration

Authorization configuration

PostgreSQL configuration

Kafka configuration

Core Kafka settings

OAuth authentication (when using SASL_PLAINTEXT)

Topic naming configuration

Kafka topics

CAS lib configuration (SpiceDB)

Service communication

Logging configuration

Secrets management

Deployment

Helm values example

Network policies

Monitoring

Health endpoints

Verify your setup

Ingress and CORS

Service route

CORS configuration

Troubleshooting

Related resources