Configuration Reference
Global configuration is provided through environment variables or a YAML config file. When deploying on Kubernetes, use a ConfigMap.
Required Variables
These variables must be set for Outpost to start:
| Variable | Description |
|---|---|
AES_ENCRYPTION_SECRET | 16, 24, or 32 byte key for AES encryption of sensitive data |
API_JWT_SECRET | Secret for signing and verifying JWTs |
API_KEY | API key for authenticating requests to the Outpost API |
REDIS_HOST | Hostname of the Redis server (default: 127.0.0.1) |
REDIS_PORT | Port of the Redis server (default: 6379) |
REDIS_DATABASE | Redis database number (default: 0) |
REDIS_TLS_ENABLED | Optional. Enable TLS for the Redis connection (default: false). |
REDIS_TLS_VERIFY | Optional. Verify the Redis server's TLS certificate against the system CA pool (default: false, i.e. the certificate is not verified). For self-signed certificates, point SSL_CERT_FILE or SSL_CERT_DIR at your CA. |
REDIS_CLUSTER_ENABLED | Optional. Enable Redis cluster mode (default: false). |
REDIS_POOL_SIZE | Optional. Connection pool size per Redis client (per node in cluster mode); default 0 uses go-redis's default of 10 per GOMAXPROCS. Raise it when Redis round-trip latency limits throughput; lower it to shrink the pool on hosts with many CPUs. |
Message Queue
Choose one message queue provider. The selected provider is used for both event delivery and log queues.
RabbitMQ:
| Variable | Description |
|---|---|
RABBITMQ_SERVER_URL | RabbitMQ connection URL (e.g., amqp://user:pass@host/vhost) |
RABBITMQ_EXCHANGE | Exchange name (default: outpost) |
AWS SQS:
| Variable | Description |
|---|---|
AWS_SQS_ACCESS_KEY_ID | AWS Access Key ID (optional; omit to use the AWS SDK default credential chain, e.g. an IAM role) |
AWS_SQS_SECRET_ACCESS_KEY | AWS Secret Access Key (optional; omit to use the AWS SDK default credential chain, e.g. an IAM role) |
AWS_SQS_REGION | AWS Region |
Whichever way you authenticate, the principal needs these actions on the Outpost queues: sqs:GetQueueUrl, sqs:SendMessage, sqs:ReceiveMessage, sqs:DeleteMessage, and sqs:ChangeMessageVisibility (the batch API variants are covered by the same actions). With auto-provisioning enabled (the default, MQS_AUTO_PROVISION=true), it also needs sqs:CreateQueue and sqs:GetQueueAttributes. If you manage the queues yourself, the first list is sufficient.
GCP Pub/Sub:
| Variable | Description |
|---|---|
GCP_PUBSUB_PROJECT | GCP Project ID |
GCP_PUBSUB_SERVICE_ACCOUNT_CREDENTIALS | Service account JSON string or file path |
Azure Service Bus:
| Variable | Description |
|---|---|
AZURE_SERVICEBUS_NAMESPACE | Azure Service Bus namespace |
AZURE_SERVICEBUS_TENANT_ID | Azure Active Directory tenant ID |
AZURE_SERVICEBUS_CLIENT_ID | Service principal client ID |
AZURE_SERVICEBUS_CLIENT_SECRET | Service principal client secret |
Publish Queue
Optional. Configures the queue Outpost consumes published events from; see Publishing Events for each provider's variables.
| Variable | Default | Description |
|---|---|---|
PUBLISH_PROXY_URL | — | HTTP CONNECT forward proxy for the publish queue connection, e.g. http://user:pass@proxy:8080. Multiple whitespace-separated URLs are tunneled in order. RabbitMQ only; other providers connect directly and ignore it. See Publish from RabbitMQ. |
Log Storage
Choose one for event log persistence:
| Variable | Description |
|---|---|
POSTGRES_URL | PostgreSQL connection URL |
CLICKHOUSE_ADDR | ClickHouse address (e.g., localhost:9000) |
CLICKHOUSE_LOG_RETENTION_TTL_DAYS | Days to retain event and delivery logs in ClickHouse (default: 0, retained indefinitely). No PostgreSQL equivalent; see the Event & Delivery Log guide. |
Delivery
| Variable | Default | Description |
|---|---|---|
DELIVERY_MAX_CONCURRENCY | 1 | Max concurrent delivery attempts |
DELIVERY_TIMEOUT_SECONDS | 5 | HTTP request timeout for webhook delivery |
MAX_RETRY_LIMIT | 10 | Max retry attempts before giving up |
RETRY_INTERVAL_SECONDS | 30 | Base interval for exponential backoff retries |
RETRY_SCHEDULE | — | Comma-separated retry delays in seconds (overrides interval/limit) |
RETRY_POLL_BACKOFF_MS | 0 (auto) | Maximum time the retry monitor sleeps between polls while idle. 0 sleeps until the next retry comes due, capped at the shorter of 30 seconds and your shortest configured retry delay, so a retry is never late. An explicit positive value is honored as a fixed maximum, which can delay a retry scheduled while the monitor is already sleeping by up to that much. |
Topics
| Variable | Default | Description |
|---|---|---|
TOPICS | — | Comma-separated list of topics your instance supports |
TOPICS_ALLOW_WILDCARDS | false | Allow * inside destination topic subscriptions, such as user.*. When disabled, stored wildcard patterns are ignored but not deleted. |
Portal
| Variable | Default | Description |
|---|---|---|
PORTAL_REFERER_URL | — | Required. URL to redirect users to when JWT expires |
PORTAL_REFRESH_URL | — | URL in your app to silently re-authenticate and generate a new JWT |
PORTAL_ORGANIZATION_NAME | — | Organization name shown in the portal header |
PORTAL_ACCENT_COLOR | — | Primary brand color (hex code, e.g., #6122E7) |
PORTAL_LOGO | — | URL for the light-mode portal logo |
PORTAL_LOGO_DARK | — | URL for the dark-mode portal logo |
PORTAL_FAVICON_URL | — | URL for the portal favicon |
PORTAL_FORCE_THEME | — | Force portal theme: light or dark |
PORTAL_DISABLE_OUTPOST_BRANDING | false | Remove the "Powered by Outpost" footer |
PORTAL_ENABLE_DESTINATION_FILTER | false | Show filter configuration UI per destination |
PORTAL_ENABLE_WEBHOOK_CUSTOM_HEADERS | false | Allow tenants to set custom HTTP headers on webhook destinations |
Alerts
| Variable | Default | Description |
|---|---|---|
ALERT_CONSECUTIVE_FAILURE_COUNT | 100 | Consecutive delivery failures before alerting on a destination (and disabling it when ALERT_AUTO_DISABLE_DESTINATION is true). Leave unset for the default of 100; set to an empty string to disable consecutive-failure alerting entirely. |
ALERT_AUTO_DISABLE_DESTINATION | false | Auto-disable a destination once ALERT_CONSECUTIVE_FAILURE_COUNT is reached. Has no effect when consecutive-failure alerting is disabled. |
ALERT_EXHAUSTED_RETRIES_WINDOW_SECONDS | 3600 | Suppression window (seconds) for exhausted_retries alerts: the first exhaustion per destination alerts and subsequent ones within the window are suppressed (0 = no suppression, alert on every exhaustion). Leave unset for the default of 3600; set to an empty string to disable exhausted_retries alerting entirely. |
Destinations
| Variable | Default | Description |
|---|---|---|
MAX_DESTINATIONS_PER_TENANT | 20 | Maximum destinations each tenant may create. Set as low as is practical for your product to limit abuse and load; lowering this value later does not remove destinations that already exist. |
DESTINATIONS_METADATA_PATH | — | Optional. Filesystem path to a directory of custom destination metadata (per-type metadata.json and instructions.md). Non-core fields such as label, description, icon, and instructions can be customized; config_fields and credential_fields cannot be overridden. |
Webhook Behavior
| Variable | Default | Description |
|---|---|---|
DESTINATIONS_WEBHOOK_MODE | default | Set to standard for Standard Webhooks compliance |
DESTINATIONS_WEBHOOK_PROXY_URL | — | Forward proxy for webhook deliveries, e.g. http://user:pass@proxy:8080. See Webhook Forward Proxy. |
DESTINATIONS_WEBHOOK_HEADER_PREFIX | x-outpost- / webhook- | Prefix for system webhook headers (event id, topic, timestamp, signature). Unless overridden, defaults to x-outpost- when DESTINATIONS_WEBHOOK_MODE is default and webhook- when standard. |
DESTINATIONS_WEBHOOK_EVENT_ID_HEADER_NAME | — | Complete name of the event ID header. Unset uses the default <prefix>event-id; an explicit value pins that exact name; an empty string disables the header. Only applies to default mode. |
DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_NAME | — | Complete name of the signature header. Unset uses the default <prefix>signature; an explicit value pins that exact name; an empty string disables the header. Only applies to default mode. |
DESTINATIONS_WEBHOOK_TIMESTAMP_HEADER_NAME | — | Complete name of the timestamp header. Unset uses the default <prefix>timestamp; an explicit value pins that exact name; an empty string disables the header. Only applies to default mode. |
DESTINATIONS_WEBHOOK_TOPIC_HEADER_NAME | — | Complete name of the topic header. Unset uses the default <prefix>topic; an explicit value pins that exact name; an empty string disables the header. |
DESTINATIONS_WEBHOOK_TIMESTAMP_FORMAT | rfc3339 / unix | Format of the timestamp header: rfc3339 or unix (seconds since the epoch). Only applies to default mode. |
DESTINATIONS_WEBHOOK_SIGNATURE_ALGORITHM | hmac-sha256 | Signature algorithm. Only applies to default mode. |
DESTINATIONS_WEBHOOK_SIGNATURE_ENCODING | hex | Encoding: hex or base64. Only applies to default mode. |
DESTINATIONS_WEBHOOK_SIGNATURE_SECRET_ENCODING | raw | How the HMAC key is derived from the destination secret: raw uses the secret string as-is, base64 and hex decode it. Only applies to default mode. |
DESTINATIONS_WEBHOOK_SIGNATURE_SECRET_PREFIX | — | Prefix stripped from the destination secret before decoding, e.g. whsec_. Ignored when the secret encoding is raw. Only applies to default mode. |
DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_HEADER_NAME | — | Name of the compat signature header. Setting it enables the compat signature: a second signature in your previous format, sent alongside the primary one while receivers migrate. See Change Webhook Signature Scheme. |
DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_CONTENT_TEMPLATE | {{.Body}} | Template for the content signed by the compat signature |
DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_HEADER_TEMPLATE | v0={{.Signatures | join ","}} | Template for the compat signature header value |
DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_ENCODING | hex | Compat signature encoding: hex or base64 |
DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_ALGORITHM | hmac-sha256 | Compat signature algorithm |
DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_SECRET_ENCODING | raw | How the compat signature derives its HMAC key from the destination secret: raw, base64 or hex |
DESTINATIONS_WEBHOOK_COMPAT_SIGNATURE_SECRET_PREFIX | — | Prefix stripped from the destination secret before decoding for the compat signature |
DESTINATIONS_WEBHOOK_COMPAT_HEADERS | — | Extra headers sent with the compat signature, as comma-separated name=template pairs ({{.EventID}}, {{.Topic}}, {{.Timestamp}}). \, is a literal comma. |
DESTINATIONS_WEBHOOK_MAX_RESPONSE_BODY_BYTES | 131072 (128 KiB) | Max bytes of a destination response body stored on the delivery attempt. Larger responses are replaced with a placeholder so the attempt log stays under the event queue's per-message size limit. Set to 0 to disable the cap. |
Observability
| Variable | Description |
|---|---|
OTEL_SERVICE_NAME | Enables OpenTelemetry when set. All three signals (traces, metrics, and logs) are exported by default; see OpenTelemetry for per-signal control |
LOG_LEVEL | Log verbosity: trace, debug, info, warn, error (default: info) |
DISABLE_TELEMETRY | Set to true to disable anonymous usage telemetry to Hookdeck |
YAML Configuration
All environment variables can also be specified in a YAML config file using snake_case keys:
aes_encryption_secret: "your-secret-here"
api_jwt_secret: "your-jwt-secret"
api_key: "your-api-key"
topics: "user.created,user.updated,order.placed"
redis:
host: "127.0.0.1"
port: 6379
database: 0
# Choose one message queue:
rabbitmq:
server_url: "amqp://user:pass@localhost/vhost"
delivery:
max_concurrency: 5
timeout_seconds: 10
portal:
referer_url: "https://yourapp.com/settings/webhooks"
organization_name: "Acme Corp"
accent_color: "#6122E7"
alert:
consecutive_failure_count: 50
exhausted_retries_window_seconds: 3600