Skip to main content
Available starting with FlowX.AI 5.6.0The Webhook Gateway is a new microservice that exposes a public endpoint for receiving incoming webhook calls from external systems. It handles webhook event ingestion and routes them to process instances via Kafka.

​
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
  • Redis for caching
  • Keycloak (or compatible OAuth2 provider) for authentication and authorization
  • SpiceDB for fine-grained authorization

​
Infrastructure prerequisites

ComponentDescription
PostgreSQLDedicated database named webhook_gateway
KafkaMessage broker for triggering process starts
RedisCaching layer for improved performance
KeycloakIdentity provider for service authentication
SpiceDBAuthorization service for workspace validation

​
Configuration

​
Authorization configuration

Set the following environment variables to connect to your identity management platform:
Environment VariableDescriptionDefault Value
SECURITY_TYPESecurity typeoauth2
SECURITY_OAUTH2_BASE_SERVER_URLBase URL of the OAuth2/OIDC server
SECURITY_OAUTH2_REALMOAuth2 realm name
SECURITY_OAUTH2_CLIENT_CLIENT_IDClient ID for token introspection
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETClient secret for token introspection
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_IDService account client IDflowx-webhook-gateway-sa
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account client secret
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URIProvider token URI${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token
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 VariableDescriptionDefault Value
SPRING_DATASOURCE_URLJDBC connection URL for PostgreSQLjdbc:postgresql://postgresql:5432/webhook_gateway
SPRING_DATASOURCE_USERNAMEDatabase usernameflowx
SPRING_DATASOURCE_PASSWORDDatabase password-
Ensure the webhook_gateway database is created before deploying the service. The Webhook Gateway will manage its own schema migrations via Liquibase.

​
Redis configuration

Webhook Gateway uses Redis for caching. Configure Redis connection using the standard Redis environment variables. Quick reference:
Environment VariableDescriptionExample ValueStatus
SPRING_DATA_REDIS_HOSTRedis server hostnamelocalhostRecommended
SPRING_DATA_REDIS_PORTRedis server port6379Recommended
SPRING_DATA_REDIS_PASSWORDRedis authentication password-Recommended
REDIS_TTLCache TTL in milliseconds5000000Optional
Both SPRING_DATA_REDIS_* and SPRING_REDIS_* variable prefixes are supported. The SPRING_DATA_REDIS_* prefix is the modern Spring Boot standard and is recommended for new deployments.
For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the Redis Configuration guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

​
Kafka configuration

The Webhook Gateway is a producer-only service — it publishes messages to Kafka but does not consume from any topics.

​
Core Kafka settings

Environment VariableDescriptionDefault Value
SPRING_KAFKA_BOOTSTRAP_SERVERSAddress of the Kafka server(s)localhost:9092
SPRING_KAFKA_SECURITY_PROTOCOLSecurity protocol for Kafka connectionsPLAINTEXT
KAFKA_AUTHEXCEPTIONRETRYINTERVALRetry interval after authorization exceptions (seconds)10

​
OAuth authentication (when using SASL_PLAINTEXT)

Environment VariableDescriptionDefault Value
KAFKA_OAUTH_CLIENT_IDOAuth client IDkafka
KAFKA_OAUTH_CLIENT_SECRETOAuth client secretkafka-secret
KAFKA_OAUTH_TOKEN_ENDPOINT_URIOAuth token endpointkafka.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 VariableDescriptionDefault Value
KAFKA_TOPIC_NAMING_PACKAGEPackage prefix for topic namesai.flowx.
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment segment for topic names
KAFKA_TOPIC_NAMING_VERSIONVersion suffix for topic names.v1
KAFKA_TOPIC_NAMING_SEPARATORPrimary separator for topic names.
KAFKA_TOPIC_NAMING_SEPARATOR2Secondary separator for topic names-

​
Kafka topics

The Webhook Gateway publishes to the following Kafka topic to trigger process starts from incoming webhook events:
Environment VariableDescriptionDefault Value
KAFKA_TOPIC_PROCESS_START_OUTTopic for triggering process starts from webhook eventsai.flowx.core.trigger.start-for-event.process.v1

​
CAS lib configuration (SpiceDB)

Environment VariableDescriptionDefault Value
FLOWX_LIB_CASCLIENT_SPICEDB_HOSTSpiceDB hostnamespicedb
FLOWX_LIB_CASCLIENT_SPICEDB_PORTSpiceDB gRPC port50051
FLOWX_LIB_CASCLIENT_SPICEDB_TOKENSpiceDB authentication token-

​
Service communication

The Webhook Gateway communicates with the following FlowX services:
Environment VariableDescriptionDefault Value
FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURLOrganization Manager base URLhttp://organization-manager:80
FLOWX_LIB_CASCLIENT_SERVICES_AUTHORIZATIONSYSTEM_BASEURLAuthorization System base URLhttp://authorization-system:80

​
Logging configuration

Environment VariableDescriptionDefault Value
LOGGING_LEVEL_ROOTRoot logging levelINFO
LOGGING_LEVEL_APPApplication-specific log levelINFO

​
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 NameDescription
SPRING_DATASOURCE_PASSWORDPostgreSQL database password
SPRING_REDIS_PASSWORDRedis authentication password
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRETKeycloak service account secret
FLOWX_LIB_CASCLIENT_SPICEDB_TOKENSpiceDB authentication token
KAFKA_OAUTH_CLIENT_SECRETKafka 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: oauth2
  SECURITY_OAUTH2_BASE_SERVER_URL: https://keycloak.example.com/auth

  # Redis
  SPRING_REDIS_HOST: redis-master

  # SpiceDB
  FLOWX_LIB_CASCLIENT_SPICEDB_HOST: spicedb
  FLOWX_LIB_CASCLIENT_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakWebhookGatewayClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_LIB_CASCLIENT_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:
ServicePurposePod Label
KafkaMessage broker communicationflowx.ai/egress-s-kafka
PostgreSQLWebhook registration storageflowx.ai/egress-s-postgresql
RedisCachingflowx.ai/egress-s-redis
KeycloakAuthenticationflowx.ai/egress-s-keycloak
SpiceDBAuthorizationflowx.ai/egress-s-spicedb
Organization ManagerOrganization context resolutionflowx.ai/egress-s-organization-manager
Authorization SystemAccess controlflowx.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

EndpointDescription
/actuator/healthHealth check endpoint
/actuator/metricsPrometheus metrics endpoint
/actuator/infoApp 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

​
Troubleshooting

Symptoms: Service fails to start with database connection errors.Solutions:
  1. Verify the webhook_gateway database exists in PostgreSQL
  2. Check that the database user has appropriate permissions
  3. Ensure network connectivity between the pod and PostgreSQL service
  4. Verify the JDBC URL format is correct
Symptoms: Authorization errors or service fails to initialize CAS client.Solutions:
  1. Verify SpiceDB is running and reachable at the configured host and port
  2. Check that the SpiceDB token is correct
  3. Ensure network policies allow gRPC traffic to SpiceDB on port 50051
  4. Review pod logs for specific CAS client error messages
Symptoms: Webhook events not triggering process starts.Solutions:
  1. Verify Kafka bootstrap servers are reachable
  2. Check that the ai.flowx.core.trigger.start-for-event.process.v1 topic exists
  3. Ensure the service has producer permissions on the topic
  4. Review pod logs for Kafka producer errors
Symptoms: External systems cannot reach the webhook URL.Solutions:
  1. Verify ingress is enabled and the /webhooks path is configured
  2. Check that network policies allow inbound traffic to the Webhook Gateway
  3. Ensure DNS resolves correctly for the webhook URL
  4. Verify the service is listening on port 8080
Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:
  1. Verify the Keycloak service account is properly configured
  2. Check that client secrets match between configuration and Keycloak
  3. Ensure the service account has required roles assigned
  4. Verify SECURITY_TYPE is set to oauth2

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

SpiceDB Configuration

Fine-grained authorization setup

Kafka Authentication

Configure Kafka security and authentication

IAM Configuration

Identity and access management setup
Last modified on March 25, 2026