Skill: 7schmiede/hookaido (version 2.6.0)

--- name: hookaido version: "2.6.0" description: >- Webhook infrastructure for receiving, queuing, and delivering webhooks. Operate Hookaido webhook ingress, durable webhook queue (SQLite/Postgres), webhook delivery (HTTP push, subprocess exec, pull API, SSE streaming), webhook signature verification (HMAC, GitHub, Gitea, Stripe, Cituro), dead-letter queue, and webhook retry policies. Use when tasks involve webhook endpoint configuration (Hookaidofile), webhook queue backends (sqlite, memory, postgres), hookaido CLI (run, config fmt, config validate, mcp serve), webhook consumption (dequeue/ack/nack/extend) over HTTP, SSE, or gRPC, subprocess webhook handlers (deliver exec), webhook provider HMAC (GitHub/Gitea/Stripe/Cituro), Admin API webhook backlog/DLQ triage, or production webhook hardening. metadata: openclaw: homepage: https://github.com/7schmiede/claw-skill-hookaido emoji: "\U0001FA9D" primaryEnv: HOOKAIDO_PULL_TOKEN requires: bins: - hookaido env: - HOOKAIDO_PULL_TOKEN - HOOKAIDO_INGRESS_SECRET install: - id: go-install kind: go package: github.com/nuetzliches/hookaido/cmd/hookaido@v2.6.0 bins: - hookaido - id: download-darwin-amd64 kind: download os: - darwin url: https://github.com/nuetzliches/hookaido/releases/download/v2.6.0/hookaido_v2.6.0_darwin_amd64.tar.gz archive: tar.gz extract: true stripComponents: 1 targetDir: ~/.local/bin bins: - hookaido label: Download hookaido v2.6.0 (macOS amd64) - id: download-darwin-arm64 kind: download os: - darwin url: https://github.com/nuetzliches/hookaido/releases/download/v2.6.0/hookaido_v2.6.0_darwin_arm64.tar.gz archive: tar.gz extract: true stripComponents: 1 targetDir: ~/.local/bin bins: - hookaido label: Download hookaido v2.6.0 (macOS arm64) - id: download-linux-amd64 kind: download os: - linux url: https://github.com/nuetzliches/hookaido/releases/download/v2.6.0/hookaido_v2.6.0_linux_amd64.tar.gz archive: tar.gz extract: true stripComponents: 1 targetDir: ~/.local/bin bins: - hookaido label: Download hookaido v2.6.0 (Linux amd64) - id: download-linux-arm64 kind: download os: - linux url: https://github.com/nuetzliches/hookaido/releases/download/v2.6.0/hookaido_v2.6.0_linux_arm64.tar.gz archive: tar.gz extract: true stripComponents: 1 targetDir: ~/.local/bin bins: - hookaido label: Download hookaido v2.6.0 (Linux arm64) - id: download-windows-amd64 kind: download os: - win32 url: https://github.com/nuetzliches/hookaido/releases/download/v2.6.0/hookaido_v2.6.0_windows_amd64.zip archive: zip extract: true targetDir: ~/.openclaw/tools/hookaido bins: - hookaido label: Download hookaido v2.6.0 (Windows amd64) - id: download-windows-arm64 kind: download os: - win32 url: https://github.com/nuetzliches/hookaido/releases/download/v2.6.0/hookaido_v2.6.0_windows_arm64.zip archive: zip extract: true targetDir: ~/.openclaw/tools/hookaido bins: - hookaido label: Download hookaido v2.6.0 (Windows arm64) --- # Hookaido ## Overview Implement and troubleshoot Hookaido with a config-first workflow: edit `Hookaidofile`, validate, run, exercise ingress/pull/exec flows, then diagnose queue health and DLQ behavior. Treat Hookaido v2.6.0's modular architecture as additive in this skill: keep the existing workflow intact by default, and opt into modules such as `postgres`, gRPC workers, subprocess delivery (`deliver exec`), or release verification only when they materially help the task. Use conservative, reversible changes and validate before runtime operations. ## Workflow 1. Confirm target topology: inbound+pull (HTTP or gRPC), push outbound, subprocess exec, or internal queue, plus the queue backend (`sqlite`, `memory`, or `postgres`). 2. Choose runtime mode and ensure `hookaido` exists where tools execute. - Host-binary mode: use the install action from `metadata.openclaw.install`. - Host fallback: run `bash {baseDir}/scripts/install_hookaido.sh` (pinned `v2.6.0`, SHA256-verified). - Public repo/source mode: use the public upstream repo `github.com/nuetzliches/hookaido` via `go install github.com/nuetzliches/hookaido/cmd/hookaido@v2.6.0` when a source-based install is preferred. - Docker-sandbox mode: use a sandbox image that already includes `hookaido` (preferred), or install inside sandbox via `agents.defaults.sandbox.docker.setupCommand`. - Keep host install actions available as fallback and to satisfy `metadata.openclaw.requires.bins`. 3. Inspect and update `Hookaidofile` minimally. 4. Run format and validation before starting or reloading: - `hookaido config fmt --config ./Hookaidofile` - `hookaido config validate --config ./Hookaidofile` - `hookaido config validate --config ./Hookaidofile --strict-secrets` when secret refs or Vault-backed config are involved. 5. Start runtime and verify health: - `hookaido run --config ./Hookaidofile --db ./.data/hookaido.db` - `hookaido run --config ./Hookaidofile --postgres-dsn "$HOOKAIDO_POSTGRES_DSN"` when `queue postgres` is selected. - `curl http://127.0.0.1:2019/healthz?details=1` 6. Validate end-to-end behavior: - ingress request accepted and queued - consumer `dequeue`/`ack`/`nack`/`extend` path works (HTTP pull, batch `ack`/`nack`, plus gRPC pull when enabled) 7. For incidents, inspect backlog and DLQ first, then mutate. ## Task Playbooks ### Configure Ingress and Pull Consumption 1. Define a route with explicit auth and pull path (HTTP pull, optional gRPC pull worker listener). 2. Keep secrets in env/file refs, never inline. 3. Verify route and global pull auth are consistent. 4. Test with a real webhook payload and a dequeue/ack cycle, using batch `ack`/`nack` when worker throughput matters. Prefer this baseline: ```hcl ingress { listen :8080 } pull_api { listen :9443 grpc_listen :9943 # optional gRPC pull-worker listener auth token env:HOOKAIDO_PULL_TOKEN } /webhooks/github { auth hmac env:HOOKAIDO_INGRESS_SECRET pull { path /pull/github } } ``` ### Configure Push Delivery 1. Use push delivery only when inbound connectivity to the service is acceptable. 2. Set timeout and retry policy explicitly. 3. Validate downstream idempotency since delivery is at-least-once. ```hcl /webhooks/stripe { auth hmac env:STRIPE_SIGNING_SECRET deliver "https://billing.internal/stripe" { retry exponential max 8 base 2s cap 2m jitter 0.2 timeout 10s } } ``` ### Configure Subprocess Delivery (`deliver exec`) 1. Use exec delivery when the target is a local script or binary, not an HTTP service. 2. Payload is piped to stdin; metadata arrives as env vars (`HOOKAIDO_ROUTE`, `HOOKAIDO_EVENT_ID`, `HOOKAIDO_ATTEMPT`, etc.). 3. Exit code determines retry behavior: `0` = ack, `1-125` = retry, `126`/`127` = immediate DLQ. 4. `sign` directives are not supported with exec (compile error). ```hcl /webhooks/github { auth hmac { provider github secret env:GITHUB_WEBHOOK_SECRET } deliver exec "/opt/hooks/deploy.sh" { timeout 30s retry exponential max 3 base 1s cap 30s jitter 0.2 env DEPLOY_ENV production env NOTIFY_URL {env.SLACK_WEBHOOK_URL} } } ``` ### Configure Provider-Compatible HMAC 1. Use `provider github`, `provider gitea`, `provider stripe`, or `provider cituro` for webhook providers with their own signature format. 2. Provider mode disables timestamp/nonce replay protection (providers do not send those headers). 3. `signature_header`, `timestamp_header`, `nonce_header`, and `tolerance` are forbidden in provider mode (compile error). ```hcl /webhooks/github { auth hmac { provider github secret env:GITHUB_WEBHOOK_SECRET } pull { path /pull/github } } /webhooks/gitea { auth hmac { provider gitea secret env:GITEA_WEBHOOK_SECRET } pull { path /pull/gitea } } /webhooks/stripe { auth hmac { provider stripe secret env:STRIPE_SIGNING_SECRET } pull { path /pull/stripe } } /webhooks/cituro { auth hmac { provider cituro secret env:CITURO_WEBHOOK_SECRET } pull { path /pull/cituro } } ``` ### Use SSE Streaming (v2.5.3+) 1. SSE replaces polling for real-time webhook delivery — use `GET {pull.path}/stream` instead of repeated `POST .../dequeue`. 2. ACK/NACK operations use the same existing POST endpoints; no protocol change. 3. Multiple concurrent SSE connections act as competing consumers. 4. Configure keepalive interval (`keepalive`) and max connection duration (`max_duration`) in the route's `pull` block. ```bash # Connect SSE stream (persistent, server pushes events) curl -sS -N "http://localhost:9443/pull/github/stream" \ -H "Authorization: Bearer $HOOKAIDO_PULL_TOKEN" # ACK received event curl -sS -X POST "http://localhost:9443/pull/github/ack" \ -H "Authorization: Bearer $HOOKAIDO_PULL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"lease_id":"lease_xyz"}' ``` ### Configure Queue Backends 1. Default to `sqlite` unless the task explicitly needs ephemeral dev mode or shared Postgres storage. 2. Treat `memory` and `postgres` as additive v2 modules, not replacements for existing sqlite workflows. 3. When using `postgres`, document the DSN source and validate health plus backlog endpoints after startup. Prefer these patterns: ```hcl queue sqlite queue memory queue postgres ``` ### Operate Queue and DLQ 1. Start with health details and backlog endpoints. 2. Inspect DLQ before requeue or delete. 3. If requeueing many items, explain expected impact and rollback path. 4. Require clear operator reason strings for mutating admin calls. Use: - `GET /healthz?details=1` - `GET /backlog/trends` - `GET /dlq` - `POST /dlq/requeue` - `POST /dlq/delete` ### Use MCP Mode for AI Operations 1. Default to `--role read` for diagnostics. 2. Enable mutations only with explicit operator intent: - `--enable-mutations --role operate --principal <identity>` 3. Enable runtime control only for admin workflows: - `--enable-runtime-control --role admin --pid-file <path>` 4. Include `reason` for mutation calls and keep it specific. #### Register as Claude Code MCP Plugin Add to `.claude/settings.json` (or `~/.claude/settings.json` for global use): ```json { "mcpServers": { "hookaido": { "command": "hookaido", "args": [ "mcp", "serve", "--config", "./Hookaidofile", "--db", "./.data/hookaido.db", "--role", "read" ] } } } ``` For operate role (queue mutations): ```json { "mcpServers": { "hookaido": { "command": "hookaido", "args": [ "mcp", "serve", "--config", "./Hookaidofile", "--db", "./.data/hookaido.db", "--enable-mutations", "--role", "operate", "--principal", "claude" ] } } } ``` The MCP server exposes structured tools directly — no shell output parsing. Claude Code discovers available tools at startup and uses them with typed parameters. ### Verify Public Releases 1. Prefer official release assets from the public Hookaido repo. 2. When supply-chain assurance matters, validate checksums, signature material, and provenance before rollout. 3. Keep verification optional by default so existing skill flows do not become heavier unless the task requires it. Use: - `hookaido verify-release --checksums ./hookaido_v2.6.0_checksums.txt --require-provenance` ## Validation Checklist - `hookaido config validate` returns success before runtime start/reload. - `hookaido config validate --strict-secrets` is used when secret refs, Vault, or public-release rollout validation matters. - Health endpoint is reachable and reports expected queue/backend state. - Pull consumer can `dequeue`, `ack`, `nack`, and `extend` with valid token (HTTP, SSE, and optional gRPC transport), including batch `ack`/`nack` when enabled. - For push mode, retry/timeout behavior is explicitly configured. - For exec mode, handler script is executable, reads stdin, and uses exit codes correctly (0=ack, non-zero=retry, 126/127=DLQ). - For `queue postgres`, runtime is started with `--postgres-dsn` or `HOOKAIDO_POSTGRES_DSN`. - Any DLQ mutation is scoped, justified, and logged. ## Safety Rules - Do not disable auth to "make tests pass." - Do not suggest direct mutations before read-only diagnostics. - Treat queue operations as at-least-once; require idempotent handlers. - Keep secrets in `env:` or `file:` refs. ## References - Read `references/operations.md` for command snippets and API payload templates.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)