Is HookRun suitable for production use?

Yes. HookRun provides token auth, HMAC signature verification, IP whitelisting, execution policies for concurrency control, built-in health checks, and hot reload — all production-ready features.

Webhook in,
action out.

Name: HookRun
Author: bluvenr

A lightweight engine that executes custom commands, scripts, and forwards webhooks based on YAML rules when webhook requests arrive. Single binary, cross-platform, open source.

Get Started View on GitHub

MIT License Cross-platform Single Binary Zero Dependencies High Performance

$hookrun validate

Validating config: config.yaml

PASS: All configurations are valid

Server port: 9000

Webhook route: /webhook

Rule files loaded: 1

- github-auto-deploy (2 rules) [auth: token]

$hookrun start

HookRun started in background (PID: 8421)

$curl -X POST .../webhook/github-auto-deploy

→ {"code":200,"rule":"push-to-main","actions":3}

Capabilities

Everything you need to automate server-side workflows from webhook events.

YAML Driven

All rules defined in YAML files. No code, no database, just config files.

Targeted Routing

/webhook/{filename} routes directly to a specific config for precise matching.

Flexible Auth

Token verification, HMAC signatures (GitHub/GitLab), and IP whitelisting with AND logic.

Multi-Condition Filters

Match headers, query params, or JSON body with eq ne contains regex.

Execution Policies

block prevents concurrency, always runs every time, cooldown for rate limiting.

Template Variables

Inject request data into commands with {{.body.ref}}, {{.header.X}}, and pass_args.

Hot Reload

Reload all YAML configurations at runtime via CLI. No restart, no downtime.

High Performance

Go-native concurrency. One binary covers Linux, macOS, and Windows with zero dependencies.

Webhook Action

Forward payloads to other services with template-based body, header whitelisting, and {{.raw_body}} support.

Relay Action

Multi-target relay to other HookRun instances with static targets, dynamic registry, and tag-based discovery.

Failure Retry

Built-in exponential backoff with jitter. Auto-retry failed commands and scripts with configurable attempts.

What Can HookRun Do?

From automated deployments to service integration, HookRun turns webhook events into actions.

Git Auto Deploy

Push to GitHub or GitLab and your server pulls, builds, and deploys automatically. No manual SSH needed.

filters: - type: "header" key: "X-GitHub-Event" operator: "eq" value: "push"

CI/CD Pipeline Trigger

Chain webhook events into multi-step build pipelines with timeout control and concurrency protection.

execution: policy: "block" actions: - type: "script" path: "./build.sh"

Monitoring Alerts

Receive alerts from Grafana, Prometheus, or any service and run automated remediation scripts.

execution: policy: "cooldown" cooldown_seconds: 300

Custom Automation

Any HTTP POST becomes a trigger. Sync data, send notifications, manage infrastructure, and more.

actions: - type: "command" cmd: "notify.sh {{.body.text}}"

Webhook Forwarding

Receive a webhook and forward it to multiple downstream services with custom headers and transformed payloads.

actions: - type: "webhook" url: "https://api.example.com/hook"

Multi-Server Deployment

Relay webhook events to multiple downstream HookRun instances with dynamic registry and tag-based discovery.

relay: targets: - tag: "prod"

Usage guide and more scenarios →

How It Works

From HTTP request to action execution in four steps.

Request

HTTP POST arrives at /webhook/{filename}

→

Authenticate

Token, HMAC signature, and IP whitelist checks

→

Match

Filters evaluate headers, query, and body

→

Execute

Commands, scripts, and webhook forwards run with request data injected

Why HookRun?

Purpose-built for webhook automation. Secure, lightweight, and fully under your control.

Security First

Token auth, HMAC signature verification, and IP whitelisting. Multiple layers of defense to keep your endpoints safe.

Lightweight

One binary, under 5MB. No database, no container runtime, no heavy dependencies. Runs anywhere with minimal resources.

Full Control

Open source under MIT. Self-hosted on your own servers. Your rules, your data, your infrastructure.

HookRun vs Alternatives

Purpose-built for webhook scenarios. See how HookRun stacks up.

	HookRun	adnanh/webhook	n8n	Huginn
Deploy Size	~3MB single file, zero deps	~7MB single file, zero deps	Docker + SQLite / PostgreSQL	Docker + MySQL / PostgreSQL
Execution Policy	`block` / `always` / `cooldown` — 3 modes	No concurrency control	Partial (retry / wait)	Scenario-based triggers
Hot Reload	Auto-watches directory, zero-config	`-hotreload` flag, single file	Restart required	Restart required
Authentication	Token + HMAC + IP whitelist	Token + HMAC	Basic / Header / JWT / IP	Devise + OAuth
Routing	`/webhook/{filename}` targeted routing	`/hooks/{id}` flat routing	Workflow engine	Scenario graph (agent links)
Process Management	Built-in CLI daemon (start/stop/status)	Requires external systemd, etc.	Docker container management	Docker container management
Config Format	YAML (readable, comments supported)	JSON / YAML	Visual editor / JSON	JSON (agent config)
Relay	Built-in multi-target + dynamic registry + tag matching	No relay support	Requires HTTP node workflow	Manual scenario proxy
Retry	Built-in exponential backoff + jitter	No retry support	Retry on Fail node	Partial (scenario-level)
Health Check	Built-in `/health` endpoint	No built-in endpoint	Has health check	Has health check
License	MIT, full freedom	MIT, full freedom	Fair-code (SUL), restrictions	MIT, full freedom

Quick Start

From download to running webhook server in three steps.

Download

# One-liner install (recommended) curl -fsSL https://bluvenr.github.io/hookrun/install.sh | bash # Or download from github.com/bluvenr/hookrun/releases

Go to GitHub Releases →

Configure

# config.yaml server: port: 9000 auth_token: "my-secret-token" hooks: deploy: actions: - cmd: "./deploy.sh"

Run

hookrun start # daemon mode hookrun start -f # foreground

More installation options (Docker, systemd, source build) and advanced usage → Full Quick Start Guide

Built For

HookRun is the right tool if you need a simple, reliable bridge between webhooks and server actions.

DevOps Engineers

Automate deployments and ops triggered by Git events without complex CI/CD pipelines.

Backend Developers

Build webhook-driven integrations without writing boilerplate HTTP handlers or webhook parsers.

SRE Teams

Run automated remediation scripts when monitoring alerts fire. Self-healing infrastructure made simple.

Indie Developers

Lightweight automation for personal servers. No Docker, no Kubernetes, just one binary.

Sys Admins

Turn incoming HTTP events into shell commands. YAML config, no scripting language required.

Small Teams

Self-hosted, open source, no SaaS dependency. Full control over your automation stack.

FAQ

Common questions about HookRun.

How does HookRun compare to adnanh/webhook?

HookRun is smaller (~3MB vs ~7MB), has built-in daemon management, directory-watch hot reload, and file-based routing for precise matching. adnanh/webhook requires external process management like systemd and offers flat /hooks/{id} routing.

Why choose HookRun over n8n or Huginn?

n8n and Huginn are heavy tools requiring Docker, databases, and GB-level deployments. HookRun is a single ~3MB binary with zero dependencies and built-in execution policies for concurrency control — ideal for webhook-to-action scenarios without container or database overhead.

What is HookRun best suited for?

Git auto-deploy, CI/CD pipeline triggers, monitoring alert responses, and personal server automation. HookRun provides execution policies (block/always/cooldown) for reliable operation in any webhook-driven scenario.

Does HookRun require Docker or a database?

No. HookRun is a single static binary with zero runtime dependencies. Download, write YAML config, and run. No Docker, no database, no container runtime needed.

Do I need to restart after changing config?

No. HookRun watches the config directory and automatically hot-reloads changes. You can also trigger reload manually via hookrun reload.

Webhook in,action out.