Configuration Reference & Step-by-Step Hook Guide¶
← Back to Home • Deployment Guide • API Reference • Operations
1. Application Configuration (config.toml)¶
webhook-async uses a single TOML file for server, worker, queue, storage, and security configuration.
[server]
host = "0.0.0.0" # Network interface to bind
port = 9000 # Listening port
url_prefix = "hooks" # Route prefix (e.g. /hooks/{id})
max_body_bytes = 10485760 # Maximum request body size (10 MB)
max_multipart_mem_bytes = 1048576 # Memory buffer limit for multipart parts (1 MB)
hook_files = ["/etc/webhook/hooks.json"]# Paths to hook definition files (JSON or YAML)
hot_reload = true # Automatically reload hook files on change
default_http_methods = ["POST"] # Fallback methods when hook omits http-methods
response_headers = [ # Global response headers added to all replies
{ name = "X-Service", value = "webhook-async" },
{ name = "Access-Control-Allow-Origin", value = "*" }
]
use_x_request_id = true # Propagate or generate X-Request-Id header
x_request_id_limit = 64 # Maximum character length for X-Request-Id
trust_proxy_headers = true # Honor X-Forwarded-For and X-Real-IP for remote-addr
[storage]
backend = "sqlite" # Storage engine: "sqlite", "valkey", or "redis"
[storage.sqlite]
database_url = "sqlite:///var/lib/webhook-async/data.db?mode=rwc"
wal_mode = true # Enable Write-Ahead Logging (WAL) for concurrency
busy_timeout_ms = 5000 # Maximum wait time on busy database locks
# Valkey / Redis configuration (uncomment when backend is "valkey" or "redis"):
# Option A: Discrete connection fields (recommended):
# [storage.valkey] # Or [storage.redis] when backend = "redis"
# host = "127.0.0.1" # Server hostname or IP address (default: "127.0.0.1")
# port = 6379 # Server port (default: 6379)
# database = 0 # Database index (0-15) or database name
# username = "webhook_worker" # ACL username (optional)
# password = "your_secret_password" # Authentication password (redacted in logs)
# tls = false # Enable TLS encryption (valkeys://)
# key_prefix = "webhook_async" # Namespaced key prefix (uses hash-tags for cluster)
#
# Option B: Single connection URL (mutually exclusive with discrete fields):
# [storage.redis]
# url = "redis://:secret@10.0.1.50:6379/0" # Accepts redis://, rediss://, valkey://, valkeys://
# key_prefix = "webhook_async" # Namespaced key prefix
[worker]
concurrency = 8 # Maximum concurrent background tasks
poll_interval_ms = 250 # Delay between queue poll attempts when idle
lease_duration_seconds = 60 # Lease window granted to worker for each claim
heartbeat_interval_seconds = 15 # Frequency at which active worker extends lease
shutdown_grace_seconds = 30 # Maximum drain duration on shutdown signal
[queue]
max_pending_jobs = 10000 # Maximum queued jobs (returns HTTP 429 when full)
default_max_attempts = 5 # Maximum execution attempts before dead-lettering
retry_base_delay_seconds = 5 # Exponential backoff base delay
retry_max_delay_seconds = 300 # Exponential backoff ceiling delay
default_timeout_seconds = 300 # Maximum execution time per command attempt
max_output_bytes = 65536 # Maximum stdout/stderr output captured (64 KB)
idempotency_retention_seconds = 86400 # Idempotency deduplication TTL (24 hours)
[ui]
enabled = true # Enable built-in Web management UI
bind = "127.0.0.1:9001" # Dedicated bind for the Web UI
path_prefix = "" # Optional URL subpath prefix (e.g. "/admin")
[auth]
admin_token = "password@123" # Direct literal password in TOML
# Or load from an environment variable (or file path):
# admin_token_env = "WEBHOOK_ADMIN_TOKEN"
# Or load from a dedicated secret file:
# admin_token_file = "/run/secrets/admin_token"
2. Step-by-Step Guide: How to Configure hooks.json¶
A hooks.json file is a JSON array of hook definition objects. Below is a progressive, step-by-step tutorial on building production-ready hooks.
Step 1: The Absolute Minimum Hook (5 Lines)¶
At its core, a hook only requires an id and an execute-command.
Create a file named hooks.json:
[
{
"id": "hello",
"execute-command": "/opt/scripts/hello.sh"
}
]
When you start the server (webhook-async server --hooks hooks.json), calling:
curl -X POST http://localhost:9000/hooks/hello
will execute /opt/scripts/hello.sh and return 200 OK.
Step 2: Set Working Directory and Restrict HTTP Methods¶
In production, scripts should execute from an explicit directory and only allow intended HTTP verbs (typically POST).
[
{
"id": "deploy-app",
"execute-command": "/opt/app/scripts/deploy.sh",
"command-working-directory": "/opt/app",
"http-methods": ["POST"]
}
]
If an unauthorized method (like GET) is sent, the server immediately returns 405 Method Not Allowed with an empty body and does not execute the command.
Step 3: Customize HTTP Responses and Output Capture¶
By default, the server returns an empty body on success. You can customize the response message or return stdout/stderr from the command directly to the caller.
[
{
"id": "ping-hook",
"execute-command": "/opt/scripts/check-health.sh",
"command-working-directory": "/opt/scripts",
"http-methods": ["POST"],
"response-message": "Health check started successfully.",
"include-command-output-in-response": true,
"include-command-output-in-response-on-error": true,
"response-headers": [
{ "name": "Content-Type", "value": "text/plain" },
{ "name": "X-Executed-By", "value": "webhook-async" }
]
}
]
include-command-output-in-response: true: The server waits for the command to finish and returns the combined stdout and stderr as the HTTP response body.include-command-output-in-response-on-error: true: If the command exits with a non-zero exit code, the HTTP response status becomes500 Internal Server Errorand includes the error output.
Step 4: Pass Dynamic Arguments to Your Command¶
Webhooks frequently receive payload data (commit IDs, branches, usernames) that must be passed as CLI arguments to your script.
Use pass-arguments-to-command:
[
{
"id": "deploy-branch",
"execute-command": "/opt/scripts/deploy.sh",
"command-working-directory": "/opt/scripts",
"http-methods": ["POST"],
"pass-arguments-to-command": [
{
"source": "payload",
"name": "ref"
},
{
"source": "payload",
"name": "head_commit.id"
},
{
"source": "url",
"name": "environment"
},
{
"source": "request",
"name": "remote-addr"
}
]
}
]
When a request arrives:
curl -X POST "http://localhost:9000/hooks/deploy-branch?environment=production" \
-H "Content-Type: application/json" \
-d '{"ref": "refs/heads/main", "head_commit": {"id": "c759720"}}'
webhook-async invokes:
/opt/scripts/deploy.sh "refs/heads/main" "c759720" "production" "127.0.0.1"
Security Note:
webhook-asyncexecutes commands via direct process invocation (execve). Arguments are passed directly in the argv array and are never interpolated into a shell string, eliminating shell injection vulnerabilities.
Step 5: Pass Values via Environment Variables¶
Passing sensitive information or large payloads through environment variables is often cleaner than positional CLI arguments.
Use pass-environment-to-command:
[
{
"id": "notify-slack",
"execute-command": "/opt/scripts/notify.sh",
"pass-environment-to-command": [
{
"source": "payload",
"name": "pusher.name",
"envname": "DEPLOY_AUTHOR"
},
{
"source": "header",
"name": "X-GitHub-Delivery",
"envname": "DELIVERY_ID"
},
{
"source": "payload",
"name": "repository.name"
}
]
}
]
Inside /opt/scripts/notify.sh, you can read:
echo "Author: $DEPLOY_AUTHOR"
echo "Delivery ID: $DELIVERY_ID"
echo "Repository: $HOOK_repository_name" # Defaults to HOOK_<name> when envname is omitted
Step 6: Write Payloads to Temporary Files¶
When tools (like kubectl, ansible, or terraform) require a file input, use pass-file-to-command. webhook-async creates a temporary file before execution, passes its absolute path in an environment variable, and automatically deletes it when execution finishes.
[
{
"id": "import-config",
"execute-command": "/opt/scripts/apply-config.sh",
"command-working-directory": "/opt/scripts",
"pass-file-to-command": [
{
"source": "entire-payload",
"envname": "CONFIG_FILE"
},
{
"source": "payload",
"name": "certificates.ssl_crt",
"envname": "CERT_PATH",
"base64decode": true
}
]
}
]
Inside /opt/scripts/apply-config.sh:
echo "Applying config from: $CONFIG_FILE"
kubectl apply -f "$CONFIG_FILE"
Step 7: Secure the Hook with Trigger Rules (trigger-rule)¶
Never expose unauthenticated webhooks to the public internet. Use trigger-rule to enforce signature verification, tokens, IP whitelists, or branch filters.
Scenario A: GitHub / GitLab HMAC-SHA256 Signature Verification¶
[
{
"id": "github-deploy",
"execute-command": "/opt/scripts/deploy.sh",
"http-methods": ["POST"],
"trigger-rule": {
"and": [
{
"match": {
"type": "payload-hmac-sha256",
"secret": "{{ getenv \"GITHUB_WEBHOOK_SECRET\" }}",
"parameter": {
"source": "header",
"name": "X-Hub-Signature-256"
}
}
},
{
"match": {
"type": "value",
"value": "refs/heads/main",
"parameter": {
"source": "payload",
"name": "ref"
}
}
}
]
}
}
]
Scenario B: Static Shared Secret / Bearer Token¶
[
{
"id": "internal-backup",
"execute-command": "/opt/scripts/run-backup.sh",
"trigger-rule": {
"match": {
"type": "value",
"value": "{{ getenv \"BACKUP_SECRET_TOKEN\" }}",
"parameter": {
"source": "header",
"name": "X-Webhook-Token"
}
}
}
}
]
Scenario C: Restricting Client IPs (CIDR Whitelist)¶
[
{
"id": "office-only-hook",
"execute-command": "/opt/scripts/restart.sh",
"trigger-rule": {
"match": {
"type": "ip-whitelist",
"ip-whitelist": "192.168.1.0/24 10.0.0.50 2001:db8::/32"
}
}
}
]
Step 8: Choose Synchronous vs. Durable Asynchronous Execution¶
By default, webhook-async operates in legacy synchronous mode (the HTTP request waits until the command finishes).
For long-running tasks (CI builds, deployments, backups), enable asynchronous mode:
[
{
"id": "async-ci-build",
"execute-command": "/opt/scripts/build-and-test.sh",
"command-working-directory": "/opt/builds",
"async": true,
"response-message": "Job enqueued for background processing."
}
]
What happens when async: true:¶
- The server validates the trigger rules and signature.
- The server serializes the command and snapshot into the durable storage queue (SQLite, Valkey, or Redis).
- The server immediately returns
HTTP 202 Acceptedwith a tracking JSON payload:json { "job_id": "018d9f10-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "status": "queued", "message": "Job enqueued for background processing." } - Background workers claim the job, execute it, heartbeat lease extensions, and handle automatic exponential backoff retries if transient errors occur.
Step 9: Use Template Expressions (-template)¶
To avoid hardcoding sensitive secrets or environment-dependent paths directly inside hooks.json, start webhook-async with the -template flag.
Supported template functions:
- {{ getenv "VAR_NAME" }}: Reads environment variable VAR_NAME (returns empty string if unset).
- {{ getenv "VAR_NAME" "default_value" }}: Reads environment variable with fallback default.
- {{ cat "/path/to/file" }}: Reads file content, trimming trailing newlines.
- {{ credential "SECRET_NAME" }}: Reads /run/credentials/$SECRET_NAME (systemd credential directory), with fallback to environment variable.
- {{ value | js }}: Escapes string safely for JSON string embedding.
Example:
[
{
"id": "secure-hook",
"execute-command": "/opt/scripts/run.sh",
"trigger-rule": {
"match": {
"type": "payload-hmac-sha256",
"secret": "{{ cat \"/etc/secrets/webhook_hmac.key\" }}",
"parameter": {
"source": "header",
"name": "X-Signature-256"
}
}
}
}
]
Step 10: Validate Your Configuration¶
Before deploying to production or reloading the service, validate your files with the built-in validator:
# Validate standard JSON/YAML hooks
webhook-async config validate --hooks /etc/webhook/hooks.json
# Validate templated hooks
webhook-async config validate --template --hooks /etc/webhook/hooks.json
If errors are present (invalid rule depth, missing required fields, syntax typos), the command prints line-specific diagnostics with non-zero exit code.
3. Parameter Extraction Reference (source)¶
Parameters can be extracted from any part of the HTTP request and mapped into command arguments, environment variables, temporary files, or trigger rule checks.
| Source | Description | Example Specification |
|---|---|---|
header |
Canonical MIME HTTP request header. Case-insensitive header lookup. | {"source": "header", "name": "X-GitHub-Event"} |
url / query |
URL query parameter string. | {"source": "url", "name": "environment"} |
payload |
Body value from JSON, XML, or Form payload. Supports dot notation (a.b.c) and array indices (items.0.id). |
{"source": "payload", "name": "repository.name"} |
raw-request-body |
The unparsed raw UTF-8 request body string. | {"source": "raw-request-body"} |
request |
Request metadata: remote-addr (client IP) or method (HTTP verb). |
{"source": "request", "name": "remote-addr"} |
string |
Static literal string value. | {"source": "string", "name": "production"} |
entire-payload |
The full raw body written to a temporary file (pass-file-to-command). |
{"source": "entire-payload", "envname": "BODY_FILE"} |
entire-headers |
JSON map of all HTTP request headers. | {"source": "entire-headers", "envname": "HEADERS_JSON"} |
entire-query |
JSON map of all URL query parameters. | {"source": "entire-query", "envname": "QUERY_JSON"} |
4. Trigger Rule Combinators and Matchers¶
Trigger rules determine whether the incoming request is authorized to execute the command.
Combinators¶
and: Array of rules; all child rules must evaluate totrue.or: Array of rules; passes if any child rule evaluates totrue.not: Inverts the boolean result of a child rule.
Matchers (match)¶
| Matcher Type | Description | Required Fields |
|---|---|---|
value |
Constant-time string equality comparison. | value, parameter |
regex |
Regular expression match against parameter value. | regex, parameter |
payload-hmac-sha1 |
HMAC-SHA1 verification against raw request body. | secret, parameter |
payload-hmac-sha256 |
HMAC-SHA256 verification against raw request body. | secret, parameter |
payload-hmac-sha512 |
HMAC-SHA512 verification against raw request body. | secret, parameter |
ip-whitelist |
Matches client IP against whitespace-delimited IPs/CIDRs. | ip-whitelist |
scalr-signature |
Validates Scalr-compliant HMAC-SHA1 timestamp and signature. | secret |