Skip to content

Getting Started

This guide walks you through installing Hookaido and running your first webhook ingress queue.

Install

Pre-built binary (no Go required):

Download the latest binary for your platform from GitHub Releases.

Build from source (requires Go 1.25+):

go build -o hookaido ./cmd/hookaido

Docker:

See Docker Quickstart for a full Docker / Docker Compose guide.

docker build -t hookaido .

Verify:

./hookaido version

Minimal Pull-Mode Setup

Pull mode is the recommended default: Hookaido receives webhooks in the DMZ, and your internal workers pull messages via outbound-only connections.

1. Create a Hookaidofile

ingress {
  listen :8080
}

pull_api {
  auth token env:HOOKAIDO_PULL_TOKEN
}

/webhooks/github {
  auth hmac env:HOOKAIDO_INGRESS_SECRET
  pull { path /pull/github }
}

This config:

  • Listens for incoming webhooks on :8080
  • Exposes a Pull API on :9443 (default) with token authentication
  • Routes POST /webhooks/github through HMAC verification, then enqueues

2. Set Environment Variables

export HOOKAIDO_PULL_TOKEN="your-pull-secret"
export HOOKAIDO_INGRESS_SECRET="your-hmac-secret"

For local development, use a dotenv file instead:

# .env
HOOKAIDO_PULL_TOKEN=devtoken
HOOKAIDO_INGRESS_SECRET=devsecret

3. Start Hookaido

./hookaido run --config ./Hookaidofile --db ./.data/hookaido.db

With dotenv:

./hookaido run --config ./Hookaidofile --db ./.data/hookaido.db --dotenv ./.env

Hookaido starts three listeners:

  • Ingress on :8080 — receives webhooks
  • Pull API on :9443 — workers consume from here
  • Admin API on 127.0.0.1:2019 — health checks, DLQ management

4. Send a Test Webhook

curl -X POST http://localhost:8080/webhooks/github \
  -H "Content-Type: application/json" \
  -d '{"action": "push", "ref": "refs/heads/main"}'

If HMAC auth is configured, you also need to send the appropriate signature headers. For testing without auth, remove the auth hmac line from your route.

5. Consume Messages

Your worker polls the Pull API:

# Dequeue a batch
curl -X POST http://localhost:9443/pull/github/dequeue \
  -H "Authorization: Bearer devtoken" \
  -H "Content-Type: application/json" \
  -d '{"batch": 10, "lease_ttl": "30s"}'

Response:

{
  "items": [
    {
      "id": "evt_abc123",
      "lease_id": "lease_xyz",
      "route": "/webhooks/github",
      "target": "pull",
      "payload_b64": "eyJhY3Rpb24iOiAicHVzaCJ9",
      "headers": { "Content-Type": "application/json" },
      "received_at": "2026-02-09T10:00:00Z",
      "attempt": 1
    }
  ]
}

After processing, acknowledge:

curl -X POST http://localhost:9443/pull/github/ack \
  -H "Authorization: Bearer devtoken" \
  -H "Content-Type: application/json" \
  -d '{"lease_id": "lease_xyz"}'

Or reject (requeue with delay):

curl -X POST http://localhost:9443/pull/github/nack \
  -H "Authorization: Bearer devtoken" \
  -H "Content-Type: application/json" \
  -d '{"lease_id": "lease_xyz", "delay": "5s"}'

Minimal Push-Mode Setup

In push mode, Hookaido delivers webhooks directly to your internal endpoints:

/webhooks/github {
  deliver https://ci.internal/build {}
}

No Pull API is needed — Hookaido handles retry, backoff, and (optional) outbound signing. See Delivery (Push) for details.

Minimal Exec-Mode Setup

Exec mode runs a local script for each webhook — no HTTP server needed on the receiving end:

/webhooks/github {
  auth hmac {
    provider github
    secret env:GITHUB_WEBHOOK_SECRET
  }

  deliver exec "./handle-webhook.sh" {
    timeout 30s
  }
}

Create a handler script:

#!/usr/bin/env bash
# handle-webhook.sh — payload arrives on stdin
PAYLOAD=$(cat)
echo "Received: $(echo "$PAYLOAD" | jq -r '.action // .ref')" >&2
# Exit 0 = ack, non-zero = retry

Start Hookaido:

export GITHUB_WEBHOOK_SECRET="your-github-secret"
chmod +x handle-webhook.sh
./hookaido run --config ./Hookaidofile --db ./.data/hookaido.db

The script runs once per webhook event. Exit code 0 acknowledges the message; any other exit code triggers a retry. See Subprocess Execution for exit code details and environment variables.

Validate Your Config

Before starting:

./hookaido config validate --config ./Hookaidofile

Format (canonical style, idempotent):

./hookaido config fmt --config ./Hookaidofile

Check Health

curl http://127.0.0.1:2019/healthz
# Detailed diagnostics:
curl http://127.0.0.1:2019/healthz?details=1

CLI Reference

Command Description
hookaido run Start the server
hookaido config fmt Format the Hookaidofile
hookaido config validate Validate config (exit code 0/1)
hookaido mcp serve Start MCP server (AI tooling)
hookaido config diff Show differences between two config files
hookaido verify-release Verify release artifact checksums and signatures
hookaido version Print version

hookaido run Flags

Flag Default Description
--config ./Hookaidofile Path to config file
--db ./.data/hookaido.db Path to SQLite database
--postgres-dsn — PostgreSQL DSN (when queue.backend is postgres)
--pid-file — Write PID file (enables SIGHUP reload)
--watch false Hot-reload on config file changes
--log-level info Runtime log level
--dotenv — Load environment variables from file

Next Steps

← Documentation Index