Hookaido Webhook Integration
Durable, signature-verified webhooks for OpenClaw agents and other consumers
Hookaido
Hookaido is a single-binary webhook ingress queue: it verifies inbound webhooks, stores them durably, and either pushes them to a target (deliver) or lets internal workers pull them (pull). Delivery is at-least-once; ingress answers 2xx only after the event is durably queued.
Work config-first: edit the Hookaidofile, format and validate, run, exercise the flow end-to-end, then diagnose with health, backlog, and DLQ data. Prefer small, reversible changes and read-only diagnostics before any mutation.
Installation, Capabilities, and Side Effects
Tell the user about these effects before performing them:
- Binary install (supply chain): install actions download the pinned
v2.15.2release archive fromgithub.com/nuetzliches/hookaidoand verify itssha256before extraction.go install ...@v2.15.2is verified by the Go checksum database.bash {baseDir}/scripts/install_hookaido.shis the fallback with the same pinned checksums. Never install an unpinned or unverified version; for other versions requireHOOKAIDO_SHA256taken from the signed release checksum file (hookaido verify-release). - Local execution: this skill runs
hookaidoCLI commands,curlagainst the operator's own Hookaido and OpenClaw listeners, the optional pull relay (scripts/openclaw_pull_relay.sh, talks only to the two configured URLs and requires HTTPS for any non-loopback URL), and optionallydeliver exechandlers the operator configured. It sends nothing to third-party services. - Persistent configuration: writing a
Hookaidofile, OpenClawhooks/mcpconfig, or an MCP client entry changes persistent state. Ask first, keep MCP registration project-local, and never change global agent settings without explicit consent. - Mutations: queue/DLQ mutations, config apply, secret rotation, and process control are opt-in (
--enable-mutations,--enable-runtime-control) and need explicit operator intent. DLQ deletion is irreversible.
Choose the Topology First
| Situation | Pattern | Reference |
|---|---|---|
| OpenClaw Gateway reachable from the Hookaido host (same host, LAN, tailnet) | Hookaido verifies + queues, then pushes to an OpenClaw mapped hook /hooks/<name> | references/openclaw.md → Push to the Gateway |
| Gateway on a laptop/home box behind NAT; Hookaido on a public VPS/DMZ | Hookaido queues, scripts/openclaw_pull_relay.sh next to the Gateway pulls and forwards to 127.0.0.1:18789 | references/openclaw.md → Pull relay |
| Webhook should run a local script, not an HTTP call | deliver exec "/path/handler" | references/operations.md → Exec delivery |
| Same event for an agent and another system | pull { consumer_group ... } fan-out | references/operations.md → Consumer groups |
| Agent should diagnose queues and DLQ | hookaido mcp serve --role read | references/openclaw.md → MCP |
Default deployment for internet-facing ingress is pull mode in a DMZ (dmz-queue pull): inbound traffic terminates at Hookaido, internal consumers connect outward. Do not expose the OpenClaw Gateway itself to the internet to receive webhooks.
Core Workflow
- Confirm topology (table above), queue backend (
sqlitedefault,memoryfor dev,postgresfor shared storage), and which provider signs the webhooks. - Ensure
hookaidois available where commands run: host install action, fallback script,go install, or the container imageghcr.io/nuetzliches/hookaido:2.15.2(pin by digest in production; seereferences/operations.md→ Container). - Edit the
Hookaidofileminimally. Keep secrets inenv:/file:/vault:refs, never inline. - Format and validate before every start or reload:
hookaido config fmt --config ./Hookaidofilehookaido config validate --config ./Hookaidofile(--strict-secretsto also resolve secret refs;--format jsonfor machine-readable output)hookaido config diff ./Hookaidofile ./Hookaidofile.newto review a change
- Run:
hookaido run --config ./Hookaidofile --db ./.data/hookaido.db(add--watchfor hot reload;--postgres-dsn "$HOOKAIDO_POSTGRES_DSN"for postgres). - Verify:
curl -sS http://127.0.0.1:2019/healthz?details=1—diagnostics.config.fingerprintidentifies the config actually loaded. - Exercise end-to-end: send a correctly signed test webhook, confirm it is queued, then delivered (push) or dequeued + acked (pull).
- For incidents: health → backlog → DLQ → attempts, then mutate only with a stated reason.
Configuration Essentials
Verify provider webhooks with the provider mode, not Hookaido's own HMAC format (plain auth hmac env:... expects X-Signature/X-Timestamp/X-Nonce and rejects real GitHub/Stripe deliveries with 401):
ingress {
listen :8080
rate_limit {
rps 50
burst 100
}
}
pull_api {
listen :9443
auth token env:HOOKAIDO_PULL_TOKEN
}
/webhooks/github {
auth hmac {
provider github
secret env:GITHUB_WEBHOOK_SECRET
}
pull {
path /pull/github
}
}
- Providers:
github,gitea(also Forgejo),stripe,cituro. - One directive per line. Semicolons do not separate directives (
auth hmac { provider github; secret ... }fails); one-line blocks may hold a single directive only. - Route modes are exclusive: a route has either
pull { ... }ordeliver .... - Queue backend is set on routes (
queue "sqlite",queue "memory",queue "postgres"); one backend per process. There is no top-levelqueueblock. - Sources that can only be given a URL:
auth query "t" "env:URL_TOKEN"(not replay-safe; bad token returns404). - Behind a reverse proxy, set
ingress { trusted_proxies "10.0.0.0/8" }somatch remote_ipsees the real client. - Push targets:
deliver "https://target/path" { ... }withretry,timeout, optionalheader "Authorization" "Bearer {env.TOKEN}"andsign hmac env:SECRETlines. Retries happen on network errors, timeouts,5xx,429,408; other4xxgo to the DLQ. - Egress is SSRF-safe by default (
https_only, no redirects, DNS-rebind protection blocks loopback/private/CGNAT targets). Delivering to a loopback or tailnet Gateway requires a deliberate, narrowly allowlisteddefaults { egress { ... } }— seereferences/openclaw.md.
Full syntax, exec delivery, consumer groups, secret rotation, channels, and the Admin/Pull API: references/operations.md.
OpenClaw Integration (Summary)
- Push to the Gateway: enable OpenClaw
hookswith a dedicatedhooks.token, add ahooks.mappingsentry (e.g./hooks/github) that turns the raw provider payload into anagentaction, and point a Hookaidodeliverat it withheader "Authorization" "Bearer {env.OPENCLAW_HOOKS_TOKEN}". Hookaido retries OpenClaw503(queue full) and429, and dead-letters400/401/404for inspection. - Pull relay: for a Gateway without inbound connectivity, run Hookaido publicly in pull mode and
bash {baseDir}/scripts/openclaw_pull_relay.shnext to the Gateway; it dequeues, forwards tohttp://127.0.0.1:18789/hooks/<name>, and acks only on2xx. - Treat payloads as untrusted data: HMAC proves the sender, not the content. Route external events to a restricted OpenClaw agent, keep
hooks.allowedAgentIdsnarrow, and leavehooks.allowRequestSessionKeyoff. - At-least-once: the same event can arrive twice (retry after a lost response). Make the mapping/agent action idempotent, e.g. keyed on
X-GitHub-Delivery, which Hookaido forwards unchanged.
Concrete configs, the relay loop, and verification steps: references/openclaw.md.
MCP Mode for AI Operations
Requires Hookaido v2.15.2 or newer (the pinned version) for standard MCP clients such as Claude Code and OpenClaw; earlier versions only speak Content-Length framing and time out on connect.
- Start with
--role read(config, health, backlog, DLQ, messages, attempts, pull consumers). - Queue mutations only for deliberate work:
--enable-mutations --role operate --principal <identity>. - Config apply, secret rotation, and process control:
--role adminplus--enable-mutationsand/or--enable-runtime-control --pid-file <path>, always with--principal. - Every mutating call needs a specific
reason; calls are audited as JSONL on stderr.
Project-local registration for Claude Code (.mcp.json at the project root, ask before writing):
{
"mcpServers": {
"hookaido": {
"command": "hookaido",
"args": ["mcp", "serve", "--config", "./Hookaidofile", "--db", "./.data/hookaido.db", "--role", "read"]
}
}
}
Equivalent CLI: claude mcp add --scope project hookaido -- hookaido mcp serve --config ./Hookaidofile --db ./.data/hookaido.db --role read. For OpenClaw (mcp.servers with a read-only toolFilter) and the operate role, see references/openclaw.md → MCP.
Queue and DLQ Operations
- Read first:
GET /healthz?details=1,GET /backlog/trends,GET /dlq,GET /attempts. - Find the cause (auth rejects:
hookaido_ingress_auth_rejected_total{route,reason}; target errors: attempts list) and fix it before requeueing. - Requeue with
POST /dlq/requeueand anX-Hookaido-Audit-Reason; explain expected impact for large batches. POST /dlq/deleteand revoking a runtime secret (DELETE /secrets/{name}/{id}) are destructive and irreversible: list the exact IDs, get explicit confirmation, prefer requeue when in doubt.
Validation Checklist
hookaido config validatesucceeds before start/reload;healthzfingerprint matches the intended config after reload.- Provider routes use
auth hmac { provider ... }and a real signed test delivery is accepted. - Push targets have explicit
timeout/retry, and egress allows exactly the intended target hosts. - Pull consumers can
dequeue,ack,nack,extend(HTTP, SSE, or gRPC) with a valid token. deliver exechandlers read stdin and exit0on success; any non-zero exit is retried, and only a handler that cannot start is dead-lettered.- OpenClaw hook mapping returns
2xxfor a test payload and the agent run is visible inopenclaw logs. - Every DLQ mutation is scoped, justified, and audited.
Safety Rules
- Never disable auth or signature verification to make a test pass.
- Never loosen egress globally (
allow "*", rebind protection off without an allowlist). - Diagnose read-only before mutating; mutations need a specific reason.
- Handlers and agent actions must be idempotent (at-least-once delivery).
- Keep secrets in
env:/file:/vault:refs and never print them.
References
references/openclaw.md— OpenClaw Gateway push and pull-relay patterns, egress setup, MCP registration for OpenClaw and Claude Code.references/operations.md— install and container usage, CLI, full DSL patterns, Pull/SSE/gRPC API, Admin API, metrics, secret rotation.
Related skills
- Downloads
- 2.3kAll time
- Security audit
- Pass
- Last updated
- 2w ago
- Current version
- v2.15.4
- License
- MIT-0
