Skip to content

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

webhook-async

webhook-async

Build & Release Latest Release License

A standalone Rust webhook receiver and asynchronous job engine.

  • Zero Runtime Dependencies: No Node.js runtime, no Python, no frontend build tools, and no mandatory Docker daemon.
  • Upstream Feature Parity: Full backward compatibility with adnanh/webhook v2.8.3 hook definitions, trigger rules, HMAC signatures, IP whitelists, and template preprocessing.
  • Dual Execution Engine:
    • Synchronous: Direct process execution returning command stdout/stderr immediately; requires zero database or queue storage.
    • Asynchronous: Durable queue committing an immutable execution snapshot before returning HTTP 202 Accepted.
  • Pluggable Storage Backends:
    • SQLite (default): Embedded, WAL-mode, multi-threaded with busy timeouts.
    • Valkey & Redis: Distributed scale-out using atomic Lua scripts and clustered hash-tagged keys.
  • Integrated Web UI: Lightweight Askama server-rendered templates, HTMX reactive components, and Server-Sent Events (SSE).
  • Process Sandboxing: Commands run with an explicit argument vector (no shell string interpolation), process group isolation (-pgid), execution timeouts, and automatic temporary file cleanup.
  • Dynamic Hot Reloading: Update hook definitions on the fly via SIGHUP, SIGUSR1, or --hotreload polling with zero downtime.

Web UI Screenshots

The built-in web management interface provides real-time visibility into queue states, running jobs, execution logs, and storage health:

Dashboard Job Details & Execution Logs
Dashboard Job Details
Filterable Jobs Queue Configured Hooks & Rules
Jobs Queue Hooks
Storage & Backend Status Secure Session Login
Storage Status Login

Documentation

Full documentation is available in docs/DEPLOYMENT.md and on the Documentation Site:

  • Deployment Guide: Production setup for Linux (systemd), Docker Compose, Kubernetes, macOS (launchd), Windows Server (NSSM), and Reverse Proxies (Caddy/Nginx).
  • Configuration Reference: Complete schema for config.toml, hook definitions, trigger rules, and template preprocessing.
  • API Reference: Receiver endpoints, health checks, administrative REST API (/api/v1/*), and SSE real-time stream.
  • Operations & Backups: Signal handling, zero-downtime hot reload, online SQLite hot backups (VACUUM INTO), logging, and disaster recovery.
  • Security Hardening: Threat model, sandboxing, timing-attack prevention, and secret management.
  • Storage Architecture: Conformance suite and storage mechanics for SQLite, Valkey, and Redis.
  • Compatibility Baseline: Feature inventory and verification evidence against adnanh/webhook v2.8.3.

Quickstart

1. Download Release

Download the precompiled standalone binary for your architecture from GitHub Releases:

# Example for Linux x86_64
curl -L -o webhook-async https://github.com/sunilsankar/webhook-async/releases/download/v1.2.0/webhook-async-linux-amd64
chmod +x webhook-async
sudo mv webhook-async /usr/local/bin/

Or build from source:

cargo build --release
sudo cp target/release/webhook-async /usr/local/bin/

2. Create a Hook Definition (hooks.json)

[
  {
    "id": "deploy-app",
    "execute-command": "/bin/echo",
    "pass-arguments-to-command": [
      { "source": "payload", "name": "ref" },
      { "source": "payload", "name": "commit" }
    ],
    "response-message": "Deployment initiated.",
    "include-command-output-in-response": true
  }
]

3. Run the Server

webhook-async server --port 9000 --hooks hooks.json

4. Trigger the Webhook

curl -X POST http://localhost:9000/hooks/deploy-app \
  -H "Content-Type: application/json" \
  -d '{"ref": "refs/heads/main", "commit": "05dc3f3"}'

Response:

refs/heads/main 05dc3f3

5. Add More Hooks (Optional)

hooks.json is an array — add as many hooks as you need, or split them across files and repeat --hooks:

webhook-async server --port 9000 --hooks hooks.json --hooks ci.yaml

Each hook is served at /hooks/<id> and can run in its own sync/async mode. See Multiple Hooks.


License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages