Cool Webhook

A self-hosted dashboard to create and manage webhooks that run Bash scripts when an HTTP URL is called, ideal for redeploys, backups, or any server-side automation.

Features

• Web UI: create, edit, and delete webhooks, with search and batch selection
• Bash scripts: define a script that executes when the webhook is triggered, with a log of each run (success, failure, and output)
• IP allowlist: restricts webhook triggers to specified IP addresses
• HTTP methods: specify how a webhook can be triggered, GET, POST, or both
• Manual trigger: run a webhook from the dashboard to test execution and review the latest run log without sending an external HTTP request
• Base URL settings: configure trigger URLs so webhooks can be invoked via IP address or a custom domain

Requirements

Tool	Version
Node.js	≥ 22.13
pnpm	9.x

Quick start

1. Install and run (development)

git clone https://github.com/khalifie/cool-webhook.git
cd cool-webhook
pnpm install
pnpm dev

Runs at http://localhost:3000.

2. Production build

pnpm build
pnpm start

The app listens on port 3000 by default.

Docker

Images are published to GitHub Container Registry on v* tags:

ghcr.io/khalifie/cool-webhook:{tag} (e.g. latest or a release tag like v1.0.0)

Docker example:

docker run -d \
  --name cool-webhook \
  -p 3000:3000 \
  -e HOST_USER="$USER" \
  -v /var/lib/cool-webhook:/var/lib/cool-webhook \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/khalifie/cool-webhook:latest

• -v /var/lib/cool-webhook: SQLite database and webhook-*.sh scripts
• -v /var/run/docker.sock: required to run scripts in a chroot on the host
• HOST_USER: Linux user that runs the script (e.g. $USER or root)

After startup, open http://{server-address}:3000.

Triggering a webhook

Each webhook has a trigger URL. Examples:

IP address

http://192.168.1.12:3000/hooks/{token}

or

Custom domain

https://example.com/hooks/{token}

Send an HTTP request with an allowed method (e.g. GET or POST). The app responds immediately and runs the script in the background.

Example:

curl -X GET "https://example.com/hooks/{token}"

Reset admin password

See docs/reset-password.md.

pnpm run reset-password

Inside the container:

docker exec -it {container-id} bash -c "pnpm run reset-password"

Contributing

See CONTRIBUTING.md.

License

This project is licensed under the MIT License.