↓Skip to main content

Hooky

Table of Contents

A lightweight HTTP webhook server written in Go. Trigger shell scripts from HTTP requests with built-in secret validation, rate limiting, and configurable execution controls. Runs standalone or in Docker.

Features #

  • Secret validation: HMAC-SHA256/SHA1/SHA512 signatures or bearer tokens
  • Trigger rules: Composable and/or/not conditions on payload fields, headers, query params, or IP ranges
  • Rate limiting: Sliding window per hook
  • Concurrency control: Limit simultaneous executions per hook
  • Command timeouts: Kill long-running commands automatically
  • Fire-and-forget: Return a response immediately and run the script in the background
  • Hot reload: Edit your config without restarting (-hotreload or SIGHUP)
  • Proxy-aware: Correct client IP resolution behind reverse proxies
  • Structured logging: JSON or text output via log/slog
  • Health endpoint: /health
  • No secret in config: Use env:VAR or file:/path to keep secrets out of config files

Installation #

Binary #

Download the latest release for your platform from the releases page:

tar -xzf hooky_*_linux_amd64.tar.gz
sudo mv hooky /usr/local/bin/

Docker #

docker pull ghcr.io/virtuallytd/hooky:latest

From source #

go install github.com/virtuallytd/hooky@latest

Quick Start #

  1. Create a hooks.yaml:
hooks:
  - id: deploy
    command: /scripts/deploy.sh
    secret:
      type: hmac-sha256
      header: X-Hub-Signature-256
      value: env:DEPLOY_SECRET
  1. Run:
DEPLOY_SECRET=mysecret hooky -hooks hooks.yaml
  1. Trigger it:
BODY='{"ref":"main"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "mysecret" | awk '{print $2}')

curl -X POST http://localhost:9000/hooks/deploy \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=$SIG" \
  -d "$BODY"

Blog Posts #