hookaido

Hookaido is a production-ready webhook infrastructure written in Go. It provides a durable queue backed by SQLite (with WAL mode), supports pull and push delivery modes, and includes built-in security features like HMAC verification, replay protection, and optional secret rotation. The MCP (AI integration) layer exposes queue state, health diagnostics, config inspection, and backlog analysis to AI assistants, enabling automated tooling and telemetry-driven operations. You run Hookaido as a single binary with a concise Hookaido file to describe how webhooks are ingested, queued, and dispatched, and you can operate and observe it through its Admin API and observability features. The server supports multiple modes (ingress for receiving webhooks, pull for DMZ-safe consumption, outbound delivery, internal job queues) and can be extended with AI-driven tooling via its MCP integration.

Prerequisites:

• Go 1.20+ (for building from source) or a prebuilt Hookaido binary
• Git
• Optional: Docker (for containerized runs)

Install from source (recommended if you want to customize or build locally):

# Clone the repository
git clone https://github.com/nuetzliches/hookaido.git
cd hookaido

# Build the CLI binary (example path from README)
go build ./cmd/hookaido

# Optional: verify build
ls -l ./hookaido

Run with a configuration file and data directory (as per Quick Start):

# Ensure you have a Hookaidofile in the working directory and a .data directory
export HOOKAIDO_PULL_TOKEN="mytoken"
./hookaido run --config Hookaidofile --db ./.data/hookaido.db

If you prefer Docker, pull and run the official image:

docker pull ghcr.io/nuetzliches/hookaido:latest
docker run -p 8080:8080 -p 9443:9443 \
  -e HOOKAIDO_PULL_TOKEN=mytoken \
  -v $(pwd)/Hookaidofile:/app/Hookaidofile:ro \
  -v hookaido-data:/app/.data \
  ghcr.io/nuetzliches/hookaido:latest

Upgrade path: pin to a release tag or digest as shown in the Quick Start section of the repository README.

Notes:

• Ensure your Hookaidofile is valid and accessible by Hookaido at runtime.
• If running in containerized environments, consider mounting a persistent data volume for the SQLite store.
• Set environment variables for secrets and tokens rather than embedding them in the config file.

Tips and caveats:

• The MCP integration exposes tools for AI assistants to inspect queue state and configurations. Use role-based access with roles like read, operate, and admin to control exposure.
• For production, enable TLS and Prometheus/OpenTelemetry observability endpoints as described in the Observability section of the README.
• If you enable the inbound (ingress) path, securely configure your ingress and ensure your signing secrets are rotated regularly.
• The default model of operation uses pull by default for DMZ-safe delivery; you can switch to push delivery by configuring the appropriate outbound/delivery blocks in Hookaidofile.
• When diagnosing issues, check the Admin API endpoints for health, backlog trends, and DLQ status, and use the MCP tooling to inspect queue configurations.