zachbg/webhook

By zachbg

•Updated 6 months ago

Receive webhooks and execute commands - GitHub, Docker Hub, Stripe, and more

Image

1.6K

Overview Tags

zachbg/webhook repository overview

⁠webhook

Lightweight webhook receiver — execute commands, forward requests, trigger Docker actions.

⁠Why?

You need to receive webhooks from GitHub, GitLab, Stripe, or any service and do something with them. This image:

Two modes — run commands or forward to URLs
Signature verification — GitHub HMAC, GitLab token, custom headers
Compiled Go binary — fast, low memory, no runtime deps
Docker-aware — includes Docker CLI for container management
Multi-hook — one container handles all your webhooks
Tiny — ~20MB

⁠Quick Start

⁠One-liner (env var mode)

docker run -d -p 9000:9000 \
  -e WEBHOOK_COMMAND="echo 'Deploy triggered!'" \
  -e WEBHOOK_SECRET=my-secret \
  zachbg/webhook

Post to http://localhost:9000/default to trigger.

⁠Config file mode

docker run -d -p 9000:9000 \
  -v ./hooks.yaml:/app/hooks.yaml \
  zachbg/webhook

⁠Docker Compose

services:
  webhook:
    image: zachbg/webhook
    ports:
      - "9000:9000"
    volumes:
      - ./hooks.yaml:/app/hooks.yaml
      - /var/run/docker.sock:/var/run/docker.sock  # For Docker commands
    restart: unless-stopped

⁠hooks.yaml

hooks:
  # Run a command when GitHub pushes
  - id: deploy
    command: "cd /app && git pull && docker compose up -d"
    secret: "github-webhook-secret"
    timeout: 120

  # Forward to Discord/Slack
  - id: notify
    forward_url: "https://discord.com/api/webhooks/xxx/yyy"
    headers:
      Content-Type: "application/json"

  # Trigger backup
  - id: backup
    command: "docker exec backup /app/scripts/backup.sh"
    secret: "backup-secret"
    timeout: 300

Each hook is accessible at http://your-server:9000/{id}.

⁠Environment Variables

Variable	Default	Description
`PORT`	`9000`	Listen port
`HOOKS_FILE`	`/app/hooks.yaml`	Path to hooks config
`WEBHOOK_COMMAND`		Command for single-hook mode
`WEBHOOK_FORWARD`		Forward URL for single-hook mode
`WEBHOOK_SECRET`		Secret for single-hook mode

⁠Signature Verification

Automatically detects and verifies:

Platform	Header	Method
GitHub	`X-Hub-Signature-256`	HMAC-SHA256
GitLab	`X-Gitlab-Token`	Token match
Generic	`X-Webhook-Secret`	Token match

⁠API

Method	Path	Description
`POST`	`/{hook-id}`	Trigger a hook
`GET`	`/health`	Health check

The webhook body is available in commands as $WEBHOOK_BODY.

⁠Examples

⁠GitHub Auto-Deploy

hooks:
  - id: deploy
    command: |
      cd /repo
      git pull origin main
      docker compose build
      docker compose up -d
    secret: "github-secret"
    timeout: 300

⁠Forward GitHub to Discord

hooks:
  - id: github-to-discord
    forward_url: "https://discord.com/api/webhooks/xxx/yyy"

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:207351ec7…

Size

19.3 MB

Last updated

6 months ago

docker pull zachbg/webhook