Webhook-Async Documentation

A standalone Rust webhook receiver and asynchronous job engine.


What is webhook-async?

webhook-async is a modern, memory-safe, standalone executable designed to receive HTTP webhooks and run tasks with complete reliability.

It solves the two biggest challenges of traditional webhook infrastructure: 1. Preserving Upstream Compatibility: Full compatibility with adnanh/webhook v2.8.3 hook definitions, trigger rules, HMAC signatures, IP whitelists, and template preprocessing. 2. Eliminating Dropped Webhooks & Timeouts: Provides a durable, transactional queue engine (SQLite, Valkey, Redis) that commits jobs before acknowledging HTTP 202 Accepted, running tasks asynchronously with retries and concurrency limits.


Core Features

  • Single Self-Contained Binary: Written in pure Rust. No Node.js runtime, no Python, no mandatory Docker engine.
  • Dual Execution Engine:
  • Synchronous: Direct process execution returning stdout/stderr immediately; requires zero database or queue storage.
  • Asynchronous: Durable queue committing an immutable execution snapshot before returning HTTP 202.
  • 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).
  • Hardened Process Execution: 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.

Architecture at a Glance

                      [ Incoming Webhook / Client ]
                                   │
                                   ▼
                       ┌────────────────────────┐
                       │   Axum HTTP Receiver   │
                       │   (Auth, Trigger Rules)│
                       └───────────┬────────────┘
                                   │
                 ┌─────────────────┴─────────────────┐
                 │ Mode Resolution                   │
                 ▼                                   ▼
        [ Synchronous Hook ]               [ Asynchronous Hook ]
                 │                                   │
                 ▼                                   ▼
       ┌──────────────────┐               ┌─────────────────────┐
       │ Direct Executor  │               │ Storage / Queue     │
       │ (Process Group)  │               │ (SQLite / Valkey)   │
       └─────────┬────────┘               └──────────┬──────────┘
                 │                                   │ (HTTP 202)
                 ▼                                   ▼
         Combined Output                    ┌─────────────────┐
          (HTTP 200/500)                    │ Worker Pool     │
                                            │ (Heartbeat, Ack)│
                                            └────────┬────────┘
                                                     ▼
                                            [ Direct Executor ]

60-Second Quickstart

1. Download the Binary

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

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

2. Define a Minimal Hook (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

Documentation Navigation

  • Deployment Guide: Step-by-step guides for Linux (systemd), Docker Compose, Kubernetes, macOS (launchd), Windows, and Reverse Proxies (Caddy/Nginx).
  • Configuration Reference: Complete schema for config.toml, hook definitions, trigger rules, parameter extraction, and template preprocessing.
  • API Reference: Complete documentation for receiver endpoints, health checks, administrative REST API (/api/v1/*), and SSE real-time stream.
  • Operations & Backups: Signal handling, zero-downtime hot reload, non-blocking SQLite hot backups (VACUUM INTO), logging, and disaster recovery.
  • Security Hardening: Threat model, sandboxing, timing-attack prevention, and secret management.
  • Troubleshooting Matrix: Common operational issues and fixes.