> ## Documentation Index > Fetch the complete documentation index at: https://getconvoy.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Configuration Convoy can be configured by using any of the following: * A configuration file -- `convoy.json` * Environment variables. * `cli flags` It is recommended to pick one configuration method and stick to it, but if you mix and match, the order of precedence is as follows: `cli flags` > `environment variables` > `convoy.json` file. Values set in the `cli flags` will override the same config values set in `environment variables`, and values set in both of them will override the same values set in your `convoy.json`. ## Redis Sentinel When using **`redis-sentinel`** as **`CONVOY_REDIS_SCHEME`** (or **`scheme`** in `convoy.json`): 1. **`CONVOY_REDIS_HOST`** — hostname or IP of a **Sentinel** (or a Kubernetes Service fronting Sentinels), **not** necessarily the Redis primary hostname. 2. **`CONVOY_REDIS_PORT`** — Sentinel port, commonly **26379**. 3. **`CONVOY_REDIS_SENTINEL_MASTER_NAME`** — logical master name Sentinels monitor (maps to **`master_name`** in `convoy.json`). 4. **`CONVOY_REDIS_PASSWORD`** — password for **Redis** after the client discovers the primary. 5. **`CONVOY_REDIS_SENTINEL_PASSWORD`** / **`CONVOY_REDIS_SENTINEL_USERNAME`** — only if Sentinels require authentication. On **Kubernetes with Helm**, you can avoid putting passwords in `values.yaml`: set **`global.externalRedis.secret`** (Redis password) and **`global.externalRedis.sentinelSecret`** (Sentinel password) to existing Secret **names**. Each Secret must include a key named **`password`**. When **`sentinelSecret`** is set, **`sentinelPassword`** in values is ignored. See [Kubernetes — Redis Sentinel](./install-convoy/kubernetes#redis-sentinel). ## Configuration Reference *** Here's the full configuration reference ```json Config theme={null} { // [optional] // Convoy uses a backwards-compatible api verisioning strategy // for the REST API. This config specifies which version your // instance should use. The environment variable equivalent is // CONVOY_API_VERSION. The default value is the latest at the time of release. "api_version": "2024-01-01", // [optional] // This is used to specify the host the server is running on. // It is used in emails with links to access the instance. // E.g. user invitation. The environment variable equivalent is // CONVOY_HOST. The default value is localhost. "host": "hooks.domain.com", // [required] // Database configuration for your instance. As of this writing, // Convoy only supports PostgreSQL. "database": { // Database host URL. The environment variable equivalent is // CONVOY_DB_HOST. The default value is localhost. "host": "localhost", // Database scheme. The environment variable equivalent is // CONVOY_DB_SCHEME. The default value is postgres. "scheme": "postgres", // Database username. The environment equivalent is // CONVOY_DB_USERNAME. The default is postgres. "username": "postgres", // Database password. The environment equivalent is // CONVOY_DB_PASSWORD. The default is postgres. "password": "postgres", // Database name. The environment equivalent is // CONVOY_DB_DATABASE. The default is convoy. "database": "convoy", // Database options. The environment equivalent is // CONVOY_DB_OPTIONS. "options": "sslmode=disable&connect_timeout=30", // Database port. The environment equivalent is // CONVOY_DB_PORT. The default value is 5432. "port": 5432 // This is used to tune the connection to the database // for maximum performance. It specifies the maximum // amount of open connections allowed in the connection pool. // The environment variable equivalent is CONVOY_DB_MAX_OPEN_CONN "max_open_conn": 10, // This is used to tune the connection to the database // for maximum performance. It specifies how many idle // connections are allowed in the connection pool. // The environment variable equivalent is CONVOY_DB_MAX_IDLE_CONN "max_idle_conn": 10, // This is used to tune the connection to the database // for maximum performance. It specifies how long any // connection is kept in the pool before being killed. // The environment variable equivalent is CONVOY_DB_CONN_MAX_LIFETIME "conn_max_lifetime": 10 // [optional] // Read replicas configuration. These are additional database // instances used for read operations, improving scalability and // performance. Each replica can also use either a DSN or // individual connection components. // The environment variable equivalent is CONVOY_DB_READ_REPLICAS "read_replicas": [ { // Read replica DSN. If provided, it takes precedence over // individual components like host, username, etc. "dsn": "postgres://convoy:convoy@localhost:5436/convoy", // Individual connection components. Ignored if DSN is specified. "host": "localhost", "username": "convoy", "password": "convoy", "database": "convoy", "port": 5436 }, { // Example of a read replica using individual components instead of a DSN. "host": "localhost", "username": "convoy", "password": "convoy", "database": "convoy", "port": 5437 } ], }, // [required] // Each Convoy component, includes a server component. This is used to // configure the server on each component. "server": { "http": { // This is a boolean flag used to determine if ssl should be // enabled or not. The environment variable equivalent is // SSL. The default value is false. "ssl": false, // This is a path used to read the ssl cert file. The environment // variable equivalent is CONVOY_SSL_CERT_FILE. If ssl is set to // true, then this must be supplied. "ssl_cert_file": "", // This is a path used to read the ssl key file. The environment // variable equivalent is CONVOY_SSL_KEY_FILE. If ssl is set to // true, then this must be supplied. "ssl_key_file": "", // This is used to configure the port the api server runs on. This // config has no effect on the other components. The environment // variable equivalent is PORT. "port": 5005, // This is used to configure the port the agent server runs on. // The environment variable equivalent is AGENT_PORT. "agent_port": 5008, // This is used to configure the port the worker server runs on. This // config has no effect on the other components. The environment // variable equivalent is WORKER_PORT. "worker_port": 5006, // This is used to configure the port the ingest server runs on. This // config has no effect on the other components. The environment // variable equivalent is INGEST_PORT. "ingest_port": 5007, // This is used to configure the port the socket server runs on. This // config has no effect on the other components. The environment // variable equivalent is SOCKET_PORT. "socket_port": 5008, // This is used to configure the forward proxy URL. This must be set // on all workers if you want to configure a forward proxy. The // environment variable equivalent is HTTP_PROXY. "http_proxy": "" } }, // [required] // Redis configuration for your instance. Convoy uses redis for // caching and enqueuing delivery. "redis": { // Redis port. The environment variable equivalent is // CONVOY_REDIS_PORT "port": 6379, // Redis host. The environment variable equivalent is // CONVOY_REDIS_HOST "host": "localhost", // Redis scheme. The environment variable equivalent is // CONVOY_REDIS_SCHEME. Can be "redis", "redis-sentinel" or "rediss". "scheme": "redis", // Redis username. The environment variable equivalent is // CONVOY_REDIS_USERNAME. "username": "redis", // Redis password. The environment variable equivalent is // CONVOY_REDIS_PASSWORD. "password": "redis", // Redis database. The environment variable equivalent is // CONVOY_REDIS_DATABASE. The default: 0 "database": 0, // [optional] // Enable TLS encryption for Redis connections. The environment // variable equivalent is CONVOY_REDIS_TLS_ENABLED. The default // value is false. "tls_enabled": false, // [optional] // Redis cluster addresses. The environment variable equivalent is // CONVOY_REDIS_ADDRESSES. The value takes precedence over the // other redis configuration in this object. The urls are fully // qualified domain names. "addresses": "{url}, {url}, ...", // [optional] // The master name for Redis Sentinel setups. Required when scheme is redis-sentinel. // The environment variable equivalent is CONVOY_REDIS_SENTINEL_MASTER_NAME. // On Kubernetes Helm, set global.externalRedis.sentinelMasterName. See "Redis Sentinel" above. "master_name": "", // [optional] // The username for Redis Sentinel setups. // The environment variable equivalent is CONVOY_REDIS_SENTINEL_USERNAME. "sentinel_username": "", // [optional] // The password for Redis Sentinel setups. // The environment variable equivalent is CONVOY_REDIS_SENTINEL_PASSWORD. "sentinel_password": "" }, // [optional] // your convoy license key, you will to specify this in order to access paid features. // The environment variable equivalent is CONVOY_LICENSE_KEY. "license_key": "", // [optional] // This is used to tune the workers pool size in our workers. // The environment variable equivalent is CONVOY_CONSUMER_POOL_SIZE. // The default value is 100. "consumer_pool_size": 100, // [optional] // This is used to enable experimental features. Check // https://getconvoy.io/docs/resources/feature-flags for all the // supported values. The environment variable equivalent is // CONVOY_ENABLE_FEATURE_FLAG "enable_feature_flag": [ "circuit-breaker" ], // [optional] // This is a boolean flag to configure profiling any Convoy component. // The environment variable equivalent is CONVOY_ENABLE_PROFILING. // The default value is false. "enable_profiling": false, // [optional] // smtp configuration is used to configure an email backend to use in // sending emails like notification emails, etc. "smtp": { // Specify the smtp provider. The environment variable equivalent is // CONVOY_SMTP_PROVIDER. "provider": "sendgrid", // Specify the smtp URL. The environment variable equivalent is // CONVOY_SMTP_URL "url": "smtp.sendgrid.net", // Specify the smtp port. The environment variable equivalent is // CONVOY_SMTP_PORT "port": 2525, // Specify the smtp username. The environment variable equivalent is // CONVOY_SMTP_USERNAME "username": "apikey", // Specify the smtp password. The environment variable equivalent is // CONVOY_SMTP_PASSWORD "password": "api-key-from-sendgrid", // Specify the smtp from email. The environment variable equivalent is // CONVOY_SMTP_FROM "from": "[email protected]" } // [optional] // Specify the retention policy configurations for your convoy instance // See the storage_policy config to configure where purged events will be stored. "retention_policy": { // Specify the period of time to go back before purging events, events within the specifed time period will not be purged. // The environment variable equivalent is CONVOY_RETENTION_POLICY "policy": "720h", // Specify whether the retention policy job should run. The environment variable equivalent is CONVOY_RETENTION_POLICY_ENABLED "enabled": false, } // [optional] // This is used to configure the logger for any Convoy component. "logger": { // This is used to configure the logging level. The supported values // are: fatal, error, warn, info, debug. The environment variable // equivalent is CONVOY_LOGGER_LEVEL. The default value is error. "level": "debug" } // [optional] // This is used to configure how we generate and push traces to. While // it is an optional object, we highly recommend it to easily spot and // fix production issues. "tracer": { // This is specifies the tracing backend to use, currently there are two // supported in-built backends: otel, sentry. The environment variable // equivalent is CONVOY_TRACER_PROVIDER "type": "otel", // This is used to configure an otel tracing backend. If type above is set // to otel, then the object needs to be fully configured. "otel": { // OTel trace generation sample rate. The environment variable // equivalent is CONVOY_OTEL_SAMPLE_RATE "sample_rate": 1.0, // OTel backend URL. Only grpc ingestion urls are supported. // The environment variable equivalent is CONVOY_OTEL_SAMPLE_RATE "collector_url": "", // Specifies if server certs should be verified or not. // The environment variable equivalent is CONVOY_OTEL_INSECURE_SKIP_VERIFY "insecure_skip_verify": true, // This is used to specify extra auth headers for specific backends. E.g. // some vendors require an api key authentication. "otel_auth": { // This is the request header key. E.g. Signoz-Api-Key. The environment // variable equivalent is CONVOY_OTEL_AUTH_HEADER_NAME. "header_name": "", // This is the request header value. The environment variable // equivalent is CONVOY_OTEL_AUTH_HEADER_VALUE. "header_value": "" } }, // This is used to configure the sentry tracing backend. If type above is set // to sentry, then this object needs to be fully configured. "sentry": { // This is used to specify the sentry DSN. The environment variable equivalent // is CONVOY_SENTRY_DSN. "dsn": "" } }, // [optional] // We use this to configure deleting events away from PostgreSQL. This config // is optional, but if you're configuring retention policies on your project, // then you need to supply it. "storage_policy": { // The type can be either s3 or on_prem. The environment variable equivalent is CONVOY_STORAGE_POLICY_TYPE. "type": "s3", // If type above is set to s3, then this config needs to be supplied. "s3": { // We use this is prefix objects from this instance to S3. The // environment variable equivalent is CONVOY_STORAGE_AWS_PREFIX. "prefix": "", // S3 Buckect name. The environment variable equivalent is // CONVOY_STORAGE_AWS_BUCKET. "bucket": "", // Bucket access key. The environment variable equivalent is // CONVOY_STORAGE_AWS_ACCESS_KEY. "access_key": "", // Bucket secret key. The environment variable equivalent is // CONVOY_STORAGE_AWS_SECRET_KEY. "secret_key": "", // Bucket region. The environment variable equivalent is // CONVOY_STORAGE_AWS_REGION. "region": "", // auth session token. The environment variable equivalent is // CONVOY_STORAGE_AWS_SESSION_TOKEN. "session_token": "", // The environment variable equivalent is CONVOY_STORAGE_AWS_ENDPOINT. "endpoint": "" }, // If type above is set to on_prem, then this config needs to be supplied. "on_prem": { // This specifies the path on the machine where pruned events are stored. // The environment variable equivalent is CONVOY_STORAGE_PREM_PATH. "path": "" } } // [optional] // This is used to configure authentication on your instance. The default values // should be fine, except you want something more custom. "auth": { // This boolean flag is used to enable/disable registration on your // instance. The environment variable equivalent is CONVOY_SIGNUP_ENABLED. "is_signup_enabled": true, "jwt": { // This is a boolean flag to enable user authentication or not. // The environment variable equivalent is CONVOY_JWT_REALM_ENABLED. // The default value is true. "enabled": true, // This is used to generate JWT tokens for UI API access. The environment // variable equivalent is CONVOY_JWT_SECRET. "secret": "", // This is used to determine how long a token is valid for in seconds. // The environment variable equivalent is CONVOY_JWT_EXPIRY. "expiry": 1800, // This is used to generate refresh JWT tokens. The environment // variable equivalent is CONVOY_JWT_REFRESH_SECRET. "refresh_secret": "", // This is used to determine how long a refresh token is valid for in seconds. // The environment variable equivalent is CONVOY_JWT_REFRESH_EXPIRY. "refresh_expiry": 3600 }, "native": { // This is a boolean flag to enable user authentication or not. // The environment variable equivalent is CONVOY_NATIVE_REALM_ENABLED. // The default value is true. "enabled": true }, "portal": { // Enables Portal Realm authentication. // The environment variable equivalent is CONVOY_PORTAL_REALM_ENABLED "enabled": true }, "google_oauth": { // Boolean flag to enable Google OAuth. // The environment variable equivalent is CONVOY_GOOGLE_OAUTH_ENABLED. "enabled": false, // Your Google OAuth Client ID. The environment variable equivalent is CONVOY_GOOGLE_OAUTH_CLIENT_ID. "client_id": "", // Your Google OAuth Redirect URL. The environment variable equivalent is CONVOY_GOOGLE_OAUTH_REDIRECT_URL. "redirect_url": "" }, "sso": { // Boolean flag to enable SSO. // The environment variable equivalent is CONVOY_SSO_ENABLED. "enabled": false, // Global SSO redirect URL. // The environment variable equivalent is CONVOY_SSO_REDIRECT_URL. "redirect_url": "" } } // [optional] // This is used to configure the server's rate limit. It defaults to 25 reqs/sec. "api_rate_limit": 25, // [optional] // This is used to configure the root path for Convoy deployments. This is useful // when deploying Convoy behind a reverse proxy with a path prefix. The environment // variable equivalent is CONVOY_ROOT_PATH. "root_path": "", // [optional] // A string specifying a custom domain suffix used for webhook portal links or ingress routing. // The environment variable equivalent is CONVOY_CUSTOM_DOMAIN_SUFFIX "custom_domain_suffix": "", // [optional] // Specifies the maximum allowed response size from the webhook endpoints in kilobytes. // Responses exceeding this limit will be truncated. The default is 50. // The environment variable equivalent is CONVOY_MAX_RESPONSE_SIZE. "max_response_size": 50, // [optional] // This is used to configure the ingestion rate limit on the data plane. Internally, // it is a distributed rate limiter implemented on Redis to ensure consistent limits // across the cluster. "instance_ingest_rate": 50 // [optional] // This is used to control the agent's execution mode. The values can be either // default, retry and events. "execution_mode": "retry" // [optional] // This is used to configure how we circuit break client endpoints. "circuit_breaker": { // This is the frequency of polling the database in seconds to calculate // an endpoint's error rate. // The environment variable equivalent is CONVOY_CIRCUIT_BREAKER_SAMPLE_RATE. "sample_rate": 10, // This is the total amount of time in seconds wait in the half-open state // to enable the endpoint to recover. // The environment variable equivalent is CONVOY_CIRCUIT_BREAKER_ERROR_TIMEOUT. "error_timeout": 60, // This is the % number of failures in the observability window, before // we tripe the circuit. // The environment variable equivalent is CONVOY_CIRCUIT_BREAKER_FAILURE_THRESHOLD. "failure_threshold": 10, // This is the total number of successes in the half-open state that'll // trigger the circuit back to a closed state. // The environment variable equivalent is CONVOY_CIRCUIT_BREAKER_SUCCESS_THRESHOLD. "success_threshold": 50, // This is the total number of requests an endpoint must have before // we begin calculating error rate. // The environment variable equivalent is CONVOY_CIRCUIT_BREAKER_MINIMUM_REQUEST_COUNT. "minimum_request_count": 15, // This is the total time window to use in calculating the endpoint error rate. // It is configured in minutes. // The environment variable equivalent is CONVOY_CIRCUIT_BREAKER_OBSERVABILITY_WINDOW. "observability_window": 30, // This is the total number of consecutive transitions to the open state // before we finally disable the endpoint. // The environment variable equivalent is CONVOY_CIRCUIT_BREAKER_CONSECUTIVE_FAILURE_THRESHOLD. "consecutive_failure_threshold": 10 } // [optional] // This configures a set of IP addresses that we can connect to. The goal // is to prevent SSRF. "dispatcher": { // This determines if the gateway accepts self-signed certificates. // The equivalent environment variable is CONVOY_DISPATCHER_INSECURE_SKIP_VERIFY. "insecure_skip_verify": false, // This is used to configure the set of IP addresses we can connect to. // The equivalent environment variable is CONVOY_DISPATCHER_ALLOW_LIST. "allow_list": [ "0.0.0.0/0", "::/0" ], // This is used to configure the set of IP addresses that are blocked. // The equivalent environment variable is CONVOY_DISPATCHER_BLOCK_LIST. "block_list": [ "127.0.0.0/8", "169.254.169.254", "::1/128" ], // [optional] Custom CA configuration for the dispatcher. // The environment variable equivalent is CONVOY_DISPATCHER_CACERT_PATH "ca_cert_path": "", // [optional] String containing the custom CA certificate logic in a single string. // The environment variable equivalent is CONVOY_DISPATCHER_CACERT_STRING "ca_cert_string": "", // The HTTP methods allowed for ping events. // The environment variable equivalent is CONVOY_DISPATCHER_PING_METHODS "ping_methods": [ "HEAD", "GET", "POST" ], // Whether to skip ping validation entirely. // The environment variable equivalent is CONVOY_DISPATCHER_SKIP_PING_VALIDATION "skip_ping_validation": false } // [optional] // This is the total time in seconds used to cap the exponential backoff // retry algorithm. For example, if set to 7200, it means we will never // exceed 2 hours in retry delay. // The equivalent environment variable is CONVOY_MAX_RETRY_SECONDS. "max_retry_seconds": 2000, // [optional] // Configure Pyroscope profiling capabilities. "pyroscope": { // Enable continuous profiling. The environment variable equivalent is CONVOY_ENABLE_PYROSCOPE_PROFILING. "enabled": false, // The environment variable equivalent is CONVOY_PYROSCOPE_URL. "url": "", // Authentication for Pyroscope. The environment variable equivalent is CONVOY_PYROSCOPE_USERNAME. "username": "", // The environment variable equivalent is CONVOY_PYROSCOPE_PASSWORD. "password": "", // Identifies the application inside your pyroscope server. // The environment variable equivalent is CONVOY_PYROSCOPE_PROFILE_ID. "profile_id": "" }, // [optional] // Advanced metrics configuration backend to push cluster metrics. "metrics": { // To enable gathering metrics. The environment variable equivalent is CONVOY_METRICS_ENABLED. "enabled": false, // Backend for metrics (default: 'prometheus'). The environment variable equivalent is CONVOY_METRICS_BACKEND. "metrics_backend": "prometheus", // Configuration specific to Prometheus metrics. "prometheus_metrics": { // How often to sample the metrics in seconds. The environment variable equivalent is CONVOY_METRICS_SAMPLE_TIME. "sample_time": 5, // Query timeout in seconds. The environment variable equivalent is CONVOY_METRICS_QUERY_TIMEOUT. "query_timeout": 30, // Interval at which materialized views are automatically refreshed. // The environment variable equivalent is CONVOY_METRICS_MATERIALIZED_VIEW_REFRESH_INTERVAL. "materialized_view_refresh_interval": 2 } }, // [optional] // HCP Vault configuration object for secrets management. "hcp_vault": { // HCP Vault Client ID. The environment variable equivalent is CONVOY_HCP_CLIENT_ID. "client_id": "", // HCP Vault Client Secret. The environment variable equivalent is CONVOY_HCP_CLIENT_SECRET. "client_secret": "", // HCP Vault Organization ID. The environment variable equivalent is CONVOY_HCP_ORG_ID. "org_id": "", // HCP Vault Project ID. The environment variable equivalent is CONVOY_HCP_PROJECT_ID. "project_id": "", // Application name mapped in HCP Vault. The environment variable equivalent is CONVOY_HCP_APP_NAME. "app_name": "", // Defines a specific secret name reference for default vault operations. // The environment variable equivalent is CONVOY_HCP_SECRET_NAME. "secret_name": "" }, // [optional] // Configure the License Service backend specifics for Enterprise setup. "license_service": { // Hosted instance of the license service. The environment variable equivalent is CONVOY_LICENSE_SERVICE_HOST. "host": "", // Path to validate tokens. The environment variable equivalent is CONVOY_LICENSE_SERVICE_VALIDATE_ENDPOINT. "validate_path": "", // Timeout duration. The environment variable equivalent is CONVOY_LICENSE_SERVICE_TIMEOUT. "timeout": "10s", // Number of retries upon error. The environment variable equivalent is CONVOY_LICENSE_SERVICE_RETRY_COUNT. "retry_count": 3 }, // [optional] // Configure standalone SSO service paths (Overwatch). "sso_service": { // Host URL of the SSO provider service. The environment variable equivalent is CONVOY_SSO_SERVICE_HOST. "host": "", // Path for OIDC/SAML redirection. The environment variable equivalent is CONVOY_SSO_SERVICE_REDIRECT_PATH. "redirect_path": "", // Path for gaining auth access tokens. The environment variable equivalent is CONVOY_SSO_SERVICE_TOKEN_PATH. "token_path": "", // Path for navigating to the admin portal endpoint. The environment variable equivalent is CONVOY_SSO_SERVICE_ADMIN_PORTAL_PATH. "admin_portal_path": "", // Request Timeout. The environment variable equivalent is CONVOY_SSO_SERVICE_TIMEOUT. "timeout": "10s", // Number of retries upon error. The environment variable equivalent is CONVOY_SSO_SERVICE_RETRY_COUNT. "retry_count": 3 } } ```