Skip to content

Hookaido Documentation

Hookaido logo

Hookaido is a webhook ingress queue — a single binary that receives webhooks, durably enqueues them, and lets your internal services consume them at their own pace. Think of it as Caddy-style simplicity for webhook infrastructure.

Key Properties

  • Single binary, no runtime dependencies.
  • Config file is the source of truth — compact Caddyfile-inspired DSL, hot-reloadable.
  • DMZ-first — ingress + queue in the DMZ, internal workers pull via outbound-only connections.
  • At-least-once delivery — ingress ACKs only after durable enqueue.
  • Pull or push — pull mode (default) or push mode with retries, backoff, and outbound signing.
  • Channel types — inbound (webhooks), outbound (API→queue→push), internal (job queues) with compile-time safety.

How It Works

graph LR
    WP[Webhook Provider] -->|POST| HK[Hookaido - DMZ<br>Ingress → Queue]
    YW[Your Worker<br>internal] -->|Pull| HK
  1. A webhook provider sends an HTTP POST to Hookaido's ingress.
  2. Hookaido authenticates the request (HMAC, basic auth, or forward auth), then durably enqueues the payload.
  3. Your internal worker pulls messages via the Pull API, processes them, and ACKs.

Alternatively, Hookaido can push (deliver) to your internal endpoints with configurable retry, backoff, and outbound HMAC signing.

Documentation

Guide Description
Getting Started Install, configure, and run your first Hookaido instance
Configuration Full DSL reference — all blocks, directives, and placeholders
Deployment Modes Pull vs push, DMZ topology, shared listeners
Ingress Route matching, authentication, rate limiting
Pull API Dequeue, ACK, NACK, extend — the consumer protocol
Admin API Health checks, DLQ, message management, backlog insights
Delivery (Push) Push dispatcher, retry policies, outbound signing
Security Secrets, TLS/mTLS, HMAC, SSRF protection
Observability Logging, Prometheus metrics, OpenTelemetry tracing
Management Model Application/endpoint labels, publish policies
Docker Quickstart Run Hookaido with Docker / Docker Compose
MCP Integration AI-assisted operations via Model Context Protocol

Requirements

  • Pre-built binaries available from GitHub Releases (no Go needed)
  • Build from source: Go 1.25+
  • Official container image: ghcr.io/nuetzliches/hookaido (for example docker pull ghcr.io/nuetzliches/hookaido:latest)
  • Docker: see Docker Quickstart