Welcome to WebHook! 中文文档

WebHook is a hardened and observable webhook-to-command runner for self-hosted, edge, and private-network environments. It keeps compatibility with adnanh/webhook hook definitions while adding production controls for command execution, traffic, auditing, and telemetry.
✨ Key Features
- 🔒 Security First: Command path whitelisting, argument validation, strict mode, and secure logging
- ⚡ High Performance: Configurable concurrency, rate limiting (including Redis-backed distributed), and optimized request handling
- 🎯 Flexible Configuration: Support for JSON and YAML configuration files with Go template support
- 🔐 Advanced Authentication: Multiple trigger rule types including HMAC signature validation, IP whitelisting, and custom rules
- 📊 Observability: Built-in Prometheus metrics, health check endpoint, optional OpenAPI spec (for Swagger/client generation), OpenTelemetry tracing, audit logging, and comprehensive logging
- 🐳 Container Ready: Official Docker images with multiple variants
- 🌍 Internationalization: Full support for English and Chinese documentation
- 🔄 Hot Reload: Update hook configurations without restarting the server
🚀 Use Cases
- CI/CD Automation: Automatically deploy applications when code is pushed to specific branches
- Service Integration: Connect GitHub, GitLab, Gitea, and other services to your infrastructure
- ChatOps: Integrate with Slack, Discord, or other messaging platforms to run commands via chat
- Monitoring & Alerts: Trigger automated responses to system events and alerts
- Custom Workflows: Build custom automation workflows tailored to your needs
🎯 How It Works
WebHook follows a simple, focused approach:
- Receive HTTP requests (GET, POST, etc.)
- Parse request headers, body, and parameters
- Validate trigger rules and conditions
- Execute configured commands with request data passed as arguments or environment variables
The commands you execute are entirely up to you - from simple scripts to complex automation workflows.
Compatibility and Scope
| Area |
Compatibility / behavior |
| Hook definitions |
Existing adnanh/webhook JSON and YAML definitions are a compatibility target and should normally load unchanged. Validate before every upgrade. |
| Historical defaults |
The default compat profile preserves the existing permissive HTTP-method and opt-in security behavior. |
| Production defaults |
-profile secure enables POST-only hooks, strict argument checks, rate limiting, request IDs, and audit logging; it also requires -allowed-command-paths. |
| Deliberate boundary |
WebHook controls local command execution. It is not a durable delivery platform and does not promise persistent queues, retries, DLQs, or restart recovery. |
🚀 Quick Start
Get up and running with WebHook in minutes.
Installation
Option 1: Homebrew or Go install
brew install soulteary/tap/webhook
# Or install directly with the Go toolchain
go install github.com/soulteary/webhook@latest
Option 2: Pre-built Binaries

Download pre-built binaries for Linux and macOS from the Releases page.
Option 3: Docker

# Latest stable core image
docker pull soulteary/webhook:latest
# Minimal scratch image (the unprefixed 7.4.0 tag is an alias)
docker pull soulteary/webhook:core-7.4.0
# Shell-script runtime
docker pull soulteary/webhook:runner-7.4.0
# Runtime with debugging and network tools
docker pull soulteary/webhook:extended-7.4.0
| Variant |
Contents |
Intended use |
core |
scratch, CA certificates, and the static WebHook binary; no shell |
Smallest production image for hooks that execute mounted static binaries |
runner |
Alpine, BusyBox utilities, Bash, and CA certificates |
Normal shell-script hooks without bundled debugging clients |
extended |
runner plus curl, jq, and yq |
Troubleshooting and scripts that explicitly need these tools |
All release variants run as UID/GID 65532 from /var/lib/webhook. The unprefixed <version> and latest tags point to core. The historical extend-<version> name remains a compatibility alias for extended-<version> since 7.2.0, but new deployments should use extended-*.
Prefer core or runner in production. extended has a deliberately larger package set and attack surface; do not select it only for interactive convenience. Ensure mounted hooks, commands, and audit paths are readable or writable by UID/GID 65532. See Container images for the complete tag and migration contract.
For a signed request you can run immediately, use the 60-second Docker Compose quickstart.
Option 4: Build from Source
git clone https://github.com/soulteary/webhook.git
cd webhook
go build
Configuration
📚 For complete documentation, see the versioned documentation site, English Documentation, or Chinese Documentation.
Create, validate, and diagnose a configuration before starting the server:
webhook init
WEBHOOK_SECRET='replace-with-a-random-secret' webhook validate --strict -template -hooks hooks/hooks.yaml
WEBHOOK_SECRET='replace-with-a-random-secret' webhook doctor --strict -template -hooks hooks/hooks.yaml
The Hook JSON Schema enables editor completion and unknown-field detection. See Configuration tools for VS Code setup and command details.
Basic Example
By default, webhook scans config files from the ./hooks directory. Create ./hooks/hooks.yaml (or ./hooks/hooks.json) to define your webhooks:
Example: Simple Deployment Hook
[
{
"id": "redeploy-webhook",
"execute-command": "/var/scripts/redeploy.sh",
"command-working-directory": "/var/webhook"
}
]
If you prefer YAML, the equivalent hooks.yaml file would look like this:
- id: redeploy-webhook
execute-command: "/var/scripts/redeploy.sh"
command-working-directory: "/var/webhook"
Running WebHook (default directory mode)
./webhook -verbose
The server will start on port 9000 by default. Your hook will be available at:
http://yourserver:9000/hooks/redeploy-webhook
Single-file mode is still supported when explicitly set:
./webhook -hooks hooks.json -verbose
Securing Your Hooks
Important: The example above has no authentication. Always use trigger rules in production!
Example: Secure Hook with an HMAC Header
[
{
"id": "secure-deploy",
"execute-command": "/var/scripts/deploy.sh",
"http-methods": ["POST"],
"trigger-rule": {
"match": {
"type": "payload-hmac-sha256",
"secret": "replace-with-a-long-random-secret",
"parameter": {
"source": "header",
"name": "X-Webhook-Signature"
}
}
}
}
]
Start with the secure profile (the command allowlist is mandatory for this profile):
./webhook -profile secure \
-allowed-command-paths=/var/scripts \
-hooks hooks.json
Send the exact request body with X-Webhook-Signature: sha256=<hex HMAC-SHA256>. Prefer loading the secret from an environment variable through a configuration template instead of committing it. Unlike query-string tokens, the signature is not copied into URLs, access logs, or browser history.
For more security options, see:
Additional Features
- Form Data Support: Parse multipart form data and file uploads - see Form Data
- Template Support: Use Go templates in configuration files with
-template flag - see Templates
- Config UI: Same binary, behavior by flags. Enable config generator Web UI with
-config-ui (recommend debugging or intranet only). It runs on the same server port (default 9000) and can be mounted with -config-ui-path (trailing slash normalized). In directory mode (default ./hooks or explicit -hooks-dir), the UI can save generated configs directly to that directory and you can validate by calling the generated endpoint immediately after save. In explicit single-file mode (-hooks), generation/download still works but save-to-directory is not exposed. The -urlprefix value is used for the call URL shown in the UI. See Webhook Parameters and Config UI.
- OwlMail integration: Receive signed email events from OwlMail, verify the request body with HMAC-SHA256, map delivery metadata for correlation, and run controlled commands. See the integration guide and runnable example.
- Provider recipes: CI-verified GitHub, GitLab, Gitea, Harbor, and Alertmanager configurations are available in example/providers.
- HTTPS: Use a reverse proxy (nginx, Traefik, Caddy) for HTTPS support
- CORS: Set custom headers including CORS headers with
-header name=value
- Hot Reload: Update configurations without restarting using
-hotreload or kill -USR1
For more examples and use cases, check out Hook Examples. Example configs and setups (hooks, Lark, multi-webhook, and OwlMail) are in the example/ directory.
Documentation
Core Documentation
Advanced Topics
Security
Release Integrity
Tagged releases publish SPDX SBOMs, a keyless Sigstore bundle for the checksum file, signed multi-architecture container manifests, and GitHub build-provenance attestations. Examples:
gh attestation verify webhook_7.4.0_linux_amd64.tar.gz -R soulteary/webhook
cosign verify-blob \
--bundle webhook_7.4.0_checksums.txt.sigstore.json \
--certificate-identity-regexp='^https://github.com/soulteary/webhook/.github/workflows/build.yml@refs/tags/.+$' \
--certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
webhook_7.4.0_checksums.txt
cosign verify \
--certificate-identity='https://github.com/soulteary/webhook/.github/workflows/build.yml@refs/tags/7.4.0' \
--certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
ghcr.io/soulteary/webhook:runner-7.4.0
About This Fork
This project is a maintained fork of the original webhook project. Current supported versions are 7.x; see SECURITY.md for the version support table.
The fork is focused on:
- Security: Regular security updates, vulnerability fixes, and enhanced security features
- Maintenance: Active development, dependency updates, and bug fixes
- Features: Community-driven improvements and new features
- Documentation: Comprehensive documentation in both English and Chinese
We aim to provide a reliable, secure, and well-maintained webhook server for the community.