Webhook in,
action out.

Name: HookRun
Author: bluvenr

A lightweight engine that executes custom commands and scripts 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.

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}}"

Usage guide and more scenarios →

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.

How It Works

From HTTP request to command 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 and scripts run with request data injected

Quick Start

From source to running webhook server in three steps.

Build

git clone https://github.com/bluvenr/hookrun.git cd HookRun go build -o hookrun ./cmd/hookrun/

Configure

# Edit config.yaml and hooks/*.yaml hookrun validate

Run

hookrun start # daemon mode hookrun start -f # foreground

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.

Webhook in,action out.