Welcome to WebHook! 中文文档

WebHook is a lightweight, secure, and highly configurable HTTP webhook server written in Go. It enables you to create HTTP endpoints that trigger custom commands or scripts based on incoming requests, making it perfect for automating deployments, CI/CD pipelines, and integrating with various services.

✨ 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:

1. Receive HTTP requests (GET, POST, etc.)
2. Parse request headers, body, and parameters
3. Validate trigger rules and conditions
4. 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.

🚀 Quick Start

Get up and running with WebHook in minutes.

Installation

Option 1: Pre-built Binaries

Download pre-built binaries for Linux, macOS, and Windows from the Releases page.

Option 2: Docker

# Latest stable version
docker pull soulteary/webhook:latest

# Specific version
docker pull soulteary/webhook:5.0.0

# Extended version with debugging tools
docker pull soulteary/webhook:extend-5.0.0

Option 3: Build from Source

git clone https://github.com/soulteary/webhook.git
cd webhook
go build

Configuration

📚 For complete documentation, see English Documentation or Chinese Documentation

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 Secret Token

[
  {
    "id": "secure-deploy",
    "execute-command": "/var/scripts/deploy.sh",
    "trigger-rule": {
      "match": {
        "type": "value",
        "value": "your-secret-token",
        "parameter": {
          "source": "url",
          "name": "token"
        }
      }
    }
  }
]

Now the hook can only be triggered with: http://yourserver:9000/hooks/secure-deploy?token=your-secret-token

For more security options, see:

• Security Best Practices - Comprehensive security guide
• Hook Rules - All available trigger rules
• Security Policy - Built-in security features

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.
• 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) are in the example/ directory.

Documentation

Core Documentation

• Hook Definition - Complete hook configuration reference
• Config UI - Config generator (enable with go run . -config-ui)
• Hook Rules - Trigger rules and conditions
• Webhook Parameters - Command-line arguments and configuration
• Templates - Using Go templates in configurations
• Referencing Request Values - Accessing request data
• Hook Examples - Practical examples and use cases

Advanced Topics

• API Reference - Complete API documentation with all endpoints
• Security Best Practices - Comprehensive security guide
• Performance Tuning - Performance optimization guide
• Testing Guide - How to run tests, generate coverage reports, and key testing scenarios
• Troubleshooting - Common issues and solutions
• Migration Guide - Upgrading from previous versions

Security

• Security Policy - Security features and vulnerability reporting

About This Fork

This project is a maintained fork of the original webhook project. Current supported versions are 5.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.