diff --git a/AGENTS.md b/AGENTS.md index 2947e9c..3202ab2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -208,23 +208,20 @@ metadata: ## Local Development -For local webhook testing, install Hookdeck CLI: +For local webhook testing, run the Hookdeck CLI via `npx` — no install required, one paste-and-run line: ```bash -# Install via npm -npm install -g hookdeck-cli - -# Or via Homebrew -brew install hookdeck/hookdeck/hookdeck +npx hookdeck-cli listen 3000 {provider} --path /webhooks/{provider} ``` -Then start the tunnel: +**Conventions for this command in skill examples (apply to every example README and any `references/setup.md` that mentions a tunnel):** -```bash -hookdeck listen 3000 --path /webhooks/{provider} -``` +- Always use `npx hookdeck-cli` (not bare `hookdeck`) — skills shouldn't push a global install of a provider-specific CLI. `npx` resolves to the package's `hookdeck` bin automatically. +- Always pass the **source name** as the second positional arg (e.g. `stripe`, `mailgun`). The CLI's `[source]` argument is required syntactically and otherwise prompts interactively; passing it explicitly gives a copy-paste-runnable command. +- Match the example's port: `3000` for Express and Next.js, `8000` for FastAPI. +- The path is `/webhooks/{provider}` matching the example handler's route. -No account required. Provides local tunnel + web UI for inspecting requests. +No account required — the CLI creates a guest account on first run and provides a local tunnel + web UI for inspecting requests. ## Related Skills @@ -755,6 +752,23 @@ providers: The test script reads scenarios from `providers.yaml` dynamically - no script modifications needed. +## Running the Generator in Sandboxed Environments + +When invoking `./scripts/generate-skills.sh generate` or `review` from a sandboxed agent environment (Claude Code on the web, Docker containers, etc.), the spawned `claude` CLI passes `--dangerously-skip-permissions` to skip its interactive permission prompts. The CLI refuses that flag when the process is running as root for safety, so the run fails immediately on every provider with: + +``` +--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons +``` + +Acknowledge the sandbox by exporting `IS_SANDBOX=1` for the generator invocation. The env var is inherited by the `claude` child processes and unblocks the flag: + +```bash +IS_SANDBOX=1 ./scripts/generate-skills.sh generate {provider} --config providers.yaml +IS_SANDBOX=1 ./scripts/generate-skills.sh review --config providers.yaml --create-pr=draft +``` + +Always pair `IS_SANDBOX=1` with an explicit `--model` (e.g. `--model claude-opus-4-7`) — the adapter's default is pinned to an older Opus build. + ## Reviewing a Provider Skill or PR When reviewing a provider skill (e.g. from a pull request or before merging): diff --git a/README.md b/README.md index d37db28..f89cd67 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ Skills for receiving and verifying webhooks from specific providers. Each includ | GitHub | [`github-webhooks`](skills/github-webhooks/) | Verify GitHub webhook signatures, handle push, pull_request, and issue events | | GitLab | [`gitlab-webhooks`](skills/gitlab-webhooks/) | Verify GitLab webhook tokens, handle push, merge_request, issue, and pipeline events | | OpenAI | [`openai-webhooks`](skills/openai-webhooks/) | Verify OpenAI webhooks for fine-tuning, batch, and realtime async events | +| OpenClaw | [`openclaw-webhooks`](skills/openclaw-webhooks/) | Verify OpenClaw Gateway webhook tokens, handle agent hook and wake event payloads | | Paddle | [`paddle-webhooks`](skills/paddle-webhooks/) | Verify Paddle webhook signatures, handle subscription and billing events | | Postmark | [`postmark-webhooks`](skills/postmark-webhooks/) | Authenticate Postmark webhooks (Basic Auth/Token), handle email delivery, bounce, open, click, and spam events | | Replicate | [`replicate-webhooks`](skills/replicate-webhooks/) | Verify Replicate webhook signatures, handle ML prediction lifecycle events | diff --git a/providers.yaml b/providers.yaml index a3ecc71..a5b8c5b 100644 --- a/providers.yaml +++ b/providers.yaml @@ -160,6 +160,23 @@ providers: - fine_tuning.job.succeeded - batch.completed + - name: openclaw + displayName: OpenClaw + docs: + webhooks: https://docs.openclaw.ai/automation/webhook + hooks: https://docs.openclaw.ai/automation/hooks + configuration: https://docs.openclaw.ai/gateway/configuration + notes: > + Open-source autonomous AI agent platform. Uses token-based authentication + (not HMAC signatures). Token sent via Authorization: Bearer or + x-openclaw-token header. Two hook types: agent hooks (/hooks/agent) trigger + isolated agent turns, wake hooks (/hooks/wake) enqueue system events. + No official webhook verification SDK — use timing-safe string comparison. + testScenario: + events: + - agent hook + - wake hook + - name: paddle displayName: Paddle docs: diff --git a/scripts/skill-generator/prompts/generate-skill.md b/scripts/skill-generator/prompts/generate-skill.md index 852126f..f6ecd17 100644 --- a/scripts/skill-generator/prompts/generate-skill.md +++ b/scripts/skill-generator/prompts/generate-skill.md @@ -66,6 +66,12 @@ Read the AGENTS.md file in this repository to understand the full skill creation 3. **Include comprehensive tests** that generate real signatures using the provider's algorithm 4. **Be idiomatic** to each framework (Express middleware patterns, Next.js App Router, FastAPI dependencies) 5. **Return appropriate HTTP status codes** (200 for success, 400 for invalid signature, etc.) +6. **Hookdeck CLI in example READMEs** — when an example shows how to receive webhooks locally, use exactly this form (no install step, source arg is required): + - Express: `npx hookdeck-cli listen 3000 {{PROVIDER_KEBAB}} --path /webhooks/{{PROVIDER_KEBAB}}` + - Next.js: `npx hookdeck-cli listen 3000 {{PROVIDER_KEBAB}} --path /webhooks/{{PROVIDER_KEBAB}}` + - FastAPI: `npx hookdeck-cli listen 8000 {{PROVIDER_KEBAB}} --path /webhooks/{{PROVIDER_KEBAB}}` + + Do **not** write `hookdeck listen ...` (assumes a global install), and do **not** omit the source positional arg (the CLI would otherwise prompt interactively). See `AGENTS.md` → "Local Development" for the rationale. ## CRITICAL: Consistency Checks