Configuration
Webhookd can be configured using either command-line flags or environment variables. Environment variables take precedence over default values, and command-line flags take precedence over both.
Environment variables are derived from the flag names by:
- Prefixing with
WHD_.
- Converting to
UPPER_SNAKE_CASE.
For example, the flag --hook-timeout corresponds to the environment variable WHD_HOOK_TIMEOUT.
Below is a comprehensive list of all configuration options, grouped by category.
Main Server Configuration
| Environment Variable |
CLI Flag |
Description |
Default |
WHD_LISTEN_ADDR |
--listen-addr |
HTTP listen address. Use :8080 for all interfaces. |
:8080 |
Hook Configuration
These settings control the behavior of script execution.
| Environment Variable |
CLI Flag |
Description |
Default |
WHD_HOOK_SCRIPTS |
--hook-scripts |
The root directory where your webhook scripts are located. |
scripts |
WHD_HOOK_DEFAULT_EXT |
--hook-default-ext |
The default file extension to look for if none is provided in the URL. |
sh |
WHD_HOOK_DEFAULT_MODE |
--hook-default-mode |
The default response mode. Can be chunked (stream) or buffered. |
chunked |
WHD_HOOK_TIMEOUT |
--hook-timeout |
Maximum time in seconds a script is allowed to run before being terminated. |
10 |
WHD_HOOK_WORKERS |
--hook-workers |
The number of concurrent workers to process hook requests. |
2 |
WHD_HOOK_LOG_DIR |
--hook-log-dir |
Directory where execution logs for each webhook are stored. |
OS temporary directory |
Logging Configuration
| Environment Variable |
CLI Flag |
Description |
Default |
WHD_LOG_LEVEL |
--log-level |
Log level for the server. Options: debug, info, warn, error. |
info |
WHD_LOG_FORMAT |
--log-format |
Log output format. Options: text, json. |
text |
WHD_LOG_MODULES |
--log-modules |
Comma-separated list of modules to activate extra logging for. Options: http (access logs), hook (script output). |
"" |
Security Configuration
| Environment Variable |
CLI Flag |
Description |
Default |
WHD_PASSWD_FILE |
--passwd-file |
Path to an .htpasswd file to enable HTTP Basic Authentication. |
.htpasswd |
WHD_TRUSTSTORE_FILE |
--truststore-file |
Path to a PEM or P12 file containing public keys for request signature verification. |
"" |
TLS Configuration
| Environment Variable |
CLI Flag |
Description |
Default |
WHD_TLS_ENABLED |
--tls-enabled |
Set to true to enable HTTPS. |
false |
WHD_TLS_CERT_FILE |
--tls-cert-file |
Path to the TLS certificate file. Ignored if a domain is set for ACME. |
server.pem |
WHD_TLS_KEY_FILE |
--tls-key-file |
Path to the TLS key file. Ignored if a domain is set for ACME. |
server.key |
WHD_TLS_DOMAIN |
--tls-domain |
A fully qualified domain name to use for automatic certificate generation via ACME (Let's Encrypt). |
"" |
Notification Configuration
| Environment Variable |
CLI Flag |
Description |
Default |
WHD_NOTIFICATION_URI |
--notification-uri |
The URI for sending post-execution notifications. See Notifications page for format. |
"" |
Static Files
| Environment Variable |
CLI Flag |
Description |
Default |
WHD_STATIC_DIR |
--static-dir |
Path to a directory of static files to serve. Disabled if empty. |
"" |
WHD_STATIC_PATH |
--static-path |
The URL path from which to serve the static files. |
/static |
Docker-Specific Configuration
These variables are used by the docker-entrypoint.sh script in the official Docker image.
| Environment Variable |
Description |
WHD_SCRIPTS_GIT_URL |
A Git repository URL (e.g., git@github.com:user/repo.git) to clone scripts from on container startup. |
WHD_SCRIPTS_GIT_KEY |
Path inside the container to the SSH private key needed to clone the repository. |