- A configuration file —
convoy.json - Environment variables.
cli flags
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 usingredis-sentinel as CONVOY_REDIS_SCHEME (or scheme in convoy.json):
CONVOY_REDIS_HOST— hostname or IP of a Sentinel (or a Kubernetes Service fronting Sentinels), not necessarily the Redis primary hostname.CONVOY_REDIS_PORT— Sentinel port, commonly 26379.CONVOY_REDIS_SENTINEL_MASTER_NAME— logical master name Sentinels monitor (maps tomaster_nameinconvoy.json).CONVOY_REDIS_PASSWORD— password for Redis after the client discovers the primary.CONVOY_REDIS_SENTINEL_PASSWORD/CONVOY_REDIS_SENTINEL_USERNAME— only if Sentinels require authentication.
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.
Configuration Reference
Here’s the full configuration reference
Config
{
// [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": "<your-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
}
}