feat: add openclaw-webhooks skill

[robinbg]

Summary

• Add a new openclaw-webhooks skill for receiving and verifying webhooks from the OpenClaw AI agent Gateway
• Includes token verification (Authorization: Bearer and x-openclaw-token headers), /hooks/agent and /hooks/wake endpoint handling
• Full skill structure following the existing pattern: SKILL.md, references (overview, setup, verification), and working examples with tests for Express, Next.js App Router, and FastAPI

Skill Structure

skills/openclaw-webhooks/
+-- SKILL.md                               # Entry point with essential code
+-- references/
|   +-- overview.md                        # Webhook concepts and architecture
|   +-- setup.md                           # Gateway configuration guide
|   +-- verification.md                    # Token verification details
+-- examples/
    +-- express/                           # Express.js with Jest tests
    +-- nextjs/                            # Next.js App Router with Vitest
    +-- fastapi/                           # Python FastAPI with pytest

Key Features

• Token-based auth with timing-safe comparison (not HMAC signature - OpenClaw uses shared secrets)
• Two endpoint types: Agent hooks (trigger isolated agent turns) and Wake hooks (system events)
• Both header styles: Authorization: Bearer and x-openclaw-token
• Query-string token rejection (matches OpenClaw Gateway behavior)
• Complete test suites for all three frameworks (Express/Next.js/FastAPI)
• Documentation sourced from official OpenClaw webhook docs

Test Plan

• Express example tests pass (npm test)
• FastAPI example tests pass (pytest)
• Next.js/Vitest tests pass (vitest run)
• SKILL.md follows existing skill format conventions
• References are complete and accurate per OpenClaw docs

Made with Cursor

[leggetter]

PR Review: feat: add openclaw-webhooks skill

Overall: Request Changes

The skill is solid in concept and security. OpenClaw is a legitimate, widely-used open-source AI agent platform with documented webhook functionality. No security vulnerabilities found. However, there are several AGENTS.md compliance issues to address.

---

Security Review ✅

No security vulnerabilities found. Good practices:

• crypto.timingSafeEqual (JS) and hmac.compare_digest (Python) for timing-safe comparison
• Graceful timingSafeEqual length mismatch handling via try/catch
• Query-string token rejection (prevents token leakage in server logs)
• Required payload field validation before processing
• Missing token/secret checks before comparison

SDK Usage ✅

OpenClaw has a TypeScript Plugin SDK (openclaw/plugin-sdk), but it's for building plugins inside the Gateway — not for verifying inbound webhooks. Since OpenClaw uses simple bearer token comparison (not HMAC signatures), there is no SDK verification method. Manual verification is the correct approach.

---

Issues to Fix

🔴 Dependency Versions (CRITICAL per AGENTS.md)

All three framework dependencies use outdated versions:

Dependency	PR Uses	AGENTS.md Requires
Next.js	14	15.x or later
Express	4.18	4.21.x or later
FastAPI	>=0.100.0	>=0.115.x or later

🔴 Missing Integration Updates (Required per checklist)

• README.md — OpenClaw not added to the Provider Skills table
• providers.yaml — No provider entry with documentation URLs and testScenario

🟡 Missing Required SKILL.md Sections

Per AGENTS.md and established patterns (stripe-webhooks, github-webhooks):

1. "Attribution" section — Should include the standard attribution comment block
2. "Recommended: webhook-handler-patterns" section — Required for all provider skills, with absolute GitHub URLs to handler-sequence, idempotency, error-handling, and retry-logic references

🟡 Response Code Inconsistency

SKILL.md documents /hooks/agent returns 202 Accepted, but:

• Express example returns 200 ❌
• Next.js example returns 200 ❌
• FastAPI example returns 202 ✅

ℹ️ Minor

• Next.js example missing tsconfig.json
• overview.md references "Mapped Webhooks" (/hooks/<name>) but SKILL.md/examples don't cover this
• Express example uses jest while most other skills use vitest

---

Summary

Category	Assessment
Useful?	✅ Yes — real, popular platform; fills a gap
Accurate?	🟡 Mostly — response code inconsistency needs fixing
SDK usage	✅ Appropriate — no SDK verification method exists
Security	✅ Good — timing-safe comparison, query-string rejection, input validation
Format compliance	🟡 Missing Attribution and Recommended sections
Dependencies	🔴 All three outdated per AGENTS.md CRITICAL guidelines
Integration	🔴 README.md and providers.yaml not updated

We have maintainer push access and will apply fixes directly to this branch. Will tag you once changes are pushed.

[leggetter]

Hi @robinbg — thanks for this contribution! We've pushed a fix commit to your branch addressing the review feedback:

Changes made:

1. Dependency versions (CRITICAL per AGENTS.md):

   • Express: ^4.18.0 → ^4.21.0
   • Next.js: ^14.0.0 → ^15.0.0 (with React/React-DOM ^19.0.0)
   • FastAPI: >=0.100.0 → >=0.115.0

2. Response code fix: Agent hook endpoints now return 202 Accepted (was 200) in Express and Next.js examples, matching the SKILL.md documentation. FastAPI was already correct.

3. Integration updates:

   • Added OpenClaw to the README.md Provider Skills table
   • Added openclaw entry to providers.yaml with docs URLs and testScenario

All 27 tests pass across Express (10), Next.js (7), and FastAPI (10).

Note: We initially flagged the Attribution and Recommended sections as missing — that was incorrect on our part; they were already present. Apologies for the noise there.

Please review the changes and let us know if you have any questions or concerns!