# Webhook — Lightweight Server for Running Shell Commands via HTTP

> A small, configurable Go server that listens for incoming HTTP webhooks and executes shell commands. Useful for automating deployments, CI/CD triggers, and integrating services that send webhook notifications.

## Install

Save as a script file and run:

# Webhook — Lightweight Server for Running Shell Commands via HTTP

## Quick Use
```bash
# Install
go install github.com/adnanh/webhook@latest
# Create hooks.json
cat > hooks.json << EOF
[
  {
    "id": "deploy",
    "execute-command": "/opt/scripts/deploy.sh",
    "command-working-directory": "/opt/app"
  }
]
EOF
# Start server
webhook -hooks hooks.json -verbose
# Trigger: curl http://localhost:9000/hooks/deploy
```

## Introduction
Webhook is a lightweight Go server that creates HTTP endpoints which trigger shell commands on the host machine. It bridges the gap between services that emit HTTP callbacks (GitHub, Docker Hub, CI systems) and local scripts that perform deployments, notifications, or data processing.

## What Webhook Does
- Creates configurable HTTP endpoints that execute commands when called
- Supports JSON, form, and header-based payload parsing
- Validates incoming requests using HMAC signatures, IP whitelists, or custom rules
- Passes request data (headers, body, query parameters) as arguments or environment variables to scripts
- Returns command output as the HTTP response body

## Architecture Overview
Webhook runs as a single Go binary that reads a JSON or YAML configuration file defining hooks. Each hook maps a URL path to a command, with optional trigger rules, argument sources, and response settings. When a matching HTTP request arrives, Webhook validates it against the configured rules, extracts parameters, and spawns the command as a subprocess. It supports concurrent execution with configurable timeouts.

## Self-Hosting & Configuration
- Install via Go, package managers (apt, brew), or download the pre-built binary from GitHub releases
- Define hooks in a JSON or YAML file with id, execute-command, and optional trigger-rule fields
- Bind to a specific address and port using -ip and -port flags
- Place behind a reverse proxy (Nginx, Caddy) for TLS termination
- Use -hotreload to pick up hook configuration changes without restarting

## Key Features
- Single static binary with zero dependencies
- Supports HMAC-SHA1/SHA256/SHA512 signature verification for GitHub and other providers
- Pass-environment and pass-arguments-to-command for flexible script integration
- Configurable response headers and status codes
- Template-based trigger rules with AND/OR/NOT logic

## Comparison with Similar Tools
- **n8n / Zapier** — Full workflow platforms; Webhook is a minimal single-purpose server
- **AWS Lambda** — Serverless functions with vendor lock-in; Webhook runs on any machine
- **Caddy with exec plugin** — Web server with command execution; Webhook is purpose-built with richer trigger rules
- **systemd path units** — File-system triggered; Webhook is HTTP-triggered with payload parsing

## FAQ
**Q: Is it safe to expose Webhook to the internet?**
A: Use trigger rules with HMAC signature validation, IP whitelists, or secret tokens to prevent unauthorized execution. Always run behind a reverse proxy with TLS.

**Q: Can I pass the request body to my script?**
A: Yes. Use pass-arguments-to-command to extract specific JSON fields, or pass the entire body via stdin or environment variables.

**Q: Does Webhook support HTTPS natively?**
A: Yes, using -secure -cert and -key flags. Alternatively, terminate TLS at a reverse proxy.

**Q: Can multiple hooks run in parallel?**
A: Yes, by default hooks execute concurrently. Use the serial flag on a hook to queue executions sequentially.

## Sources
- https://github.com/adnanh/webhook
- https://github.com/adnanh/webhook/blob/master/docs/Hook-Definition.md

---
Source: https://tokrepo.com/en/workflows/7890a092-3b41-11f1-9bc6-00163e2b0d79
Author: Script Depot