hookdeck · leggetter · Feb 22, 2026 · Feb 22, 2026 · Feb 22, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -308,10 +308,11 @@ Server runs on http://localhost:3000
 - Be idiomatic to the framework and language (Express examples should look like Express code, FastAPI should be Pythonic, Next.js should follow Next.js conventions)
 - Include only the code needed to demonstrate webhook handling
 - Add inline comments explaining key concepts (signature verification, event parsing)
-- **Prefer manual signature verification** — SDK methods can have undocumented parameter names or change between versions; manual verification is more reliable and educational
-- If showing SDK verification, **always verify the exact method signature against official docs** — parameter names like `secret` vs `webhookSecret` or header key formats can cause silent failures
+- **Use the provider's official SDK for signature verification when available** — it's the recommended approach, stays aligned with provider changes, and handles edge cases correctly (e.g., secret rotation, multiple signatures)
+- **Include manual verification as a fallback** for frameworks or languages the SDK doesn't support (e.g., FastAPI when the provider only has a Node SDK)
+- **Always use raw body** for verification — whether using SDK or manual, the signed content is the raw request body
+- When using the SDK, **verify the exact method signature against official docs** — parameter names like `secret` vs `webhookSecret` or header key formats can cause silent failures
 - Show proper error handling (return appropriate status codes)
-- Keep dependencies minimal (avoid adding SDK just for verification if manual works)
 
 ### Dependency Version Guidelines
 
@@ -416,8 +417,14 @@ For the complete list of events, see [{Provider}'s webhook documentation]({url})
 
 ## Implementation
 
+### SDK Verification (when available)
+
 {Code showing verification with official SDK}
 
+### Manual Verification (fallback for unsupported frameworks)
+
+{Code for manual verification when SDK doesn't support the framework}
+
 ## Common Gotchas
 
 - {Gotcha 1: e.g., raw body parsing}
@@ -490,12 +497,14 @@ Gather this information:
 - Header name(s): (e.g., X-Provider-Signature, Stripe-Signature)
 - Secret format: (e.g., whsec_xxx, starts with sk_)
 
-### SDK Verification Method (if using SDK)
+### SDK Verification Method (preferred when available)
 - Package name: (e.g., stripe, @octokit/webhooks)
 - Method signature: (exact parameters and their names)
 - Example: `provider.webhooks.verify({ payload, headers: {id, timestamp, signature}, webhookSecret })`
+- Which frameworks/languages does the SDK support? (Node.js only? Python? Both?)
 
-### Manual Verification (recommended for examples)
+### Manual Verification (fallback for unsupported frameworks)
+- Use when the provider's SDK doesn't support the framework (e.g., FastAPI when SDK is Node-only)
 - Signed content format: (e.g., "{timestamp}.{payload}", "{header}.{payload}")
 - Signature comparison: (timing-safe, base64 decode, etc.)
 
@@ -509,11 +518,9 @@ Gather this information:
 - (e.g., "Header names are lowercase in some frameworks")
 ```
 
-**Why manual verification is often better for examples:**
-- SDK APIs change and documentation may be outdated
-- Manual verification is more educational (shows exactly how it works)
-- Fewer dependencies (don't need full SDK just for verification)
-- Works consistently across all languages/frameworks
+**When to use SDK vs manual:**
+- **SDK (default):** Use when the provider offers a well-maintained SDK with webhook verification. It stays aligned with provider changes and handles edge cases.
+- **Manual (fallback):** Use when the SDK doesn't support the framework (e.g., Python/FastAPI when only Node SDK exists), or when no SDK exists. Document the signing algorithm clearly so implementers can verify manually.
 
 ### Step-by-Step Process
 
@@ -522,7 +529,7 @@ Gather this information:
 3. Add SKILL.md following the provider skill template:
    - Frontmatter with name, description, license, metadata
    - "When to Use This Skill" section
-   - "Essential Code" section with inline examples (show both SDK and manual verification)
+   - "Essential Code" section with inline examples (SDK for supported frameworks, manual for fallback)
    - "Common Event Types" table
    - "Environment Variables" section
    - "Local Development" section with Hookdeck CLI
@@ -531,9 +538,9 @@ Gather this information:
 4. Add reference files in `references/`:
    - `overview.md` - What the webhooks are, common events
    - `setup.md` - Dashboard configuration, signing secret
-   - `verification.md` - Signature verification details (include manual verification code)
+   - `verification.md` - Signature verification details (SDK preferred, manual fallback for unsupported frameworks)
 5. Create examples for Express, Next.js, and FastAPI in `examples/`
-   - **Prefer manual signature verification** over SDK methods (more reliable, educational, fewer dependencies)
+   - **Use the provider's SDK for verification** when it supports the framework; **include manual verification** for frameworks the SDK doesn't support
    - Include comprehensive tests for each example
 6. Run example tests locally: `cd examples/express && npm test` (repeat for each framework)
 7. Update integration files:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -502,7 +502,7 @@ See [AGENTS.md](AGENTS.md) for detailed technical guidelines. Key points:
 "test": "vitest"       // ✗ Hangs in watch mode
 ```
 
-**Signature Verification:** Prefer manual verification over SDK methods — it's more reliable and educational.
+**Signature Verification:** Use the provider's official SDK when available; include manual verification as a fallback for frameworks the SDK doesn't support (e.g., FastAPI when only Node SDK exists).
 
 **Event Names:** Must match official documentation exactly. Common mistakes:
 - Underscores vs dots vs spaces (`spam_report` vs `spam.report` vs `spam report`)

diff --git a/scripts/skill-generator/prompts/generate-skill.md b/scripts/skill-generator/prompts/generate-skill.md
@@ -61,8 +61,8 @@ Read the AGENTS.md file in this repository to understand the full skill creation
 
 ## Important Guidelines
 
-1. **Prefer manual signature verification** over SDK methods - it's more reliable and educational
-2. **Use raw body** for signature verification - don't parse JSON before verifying
+1. **Use the provider's official SDK** for signature verification when it supports the framework; **include manual verification** as a fallback for frameworks the SDK doesn't support (e.g., FastAPI when only Node SDK exists)
+2. **Use raw body** for signature verification - don't parse JSON before verifying (SDK or manual)
 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.)
@@ -77,7 +77,7 @@ Read the AGENTS.md file in this repository to understand the full skill creation
 4. **Environment variable names** - Consistent across .env.example and code files
 
 **Check for these common mistakes:**
-- SKILL.md shows one verification approach, examples use a different one
+- Verification logic is inconsistent (e.g., SKILL.md and examples use different signed content format or algorithm)
 - overview.md lists different events than the code handles
 - setup.md describes headers that don't match the code
 

diff --git a/skills/hookdeck-event-gateway/SKILL.md b/skills/hookdeck-event-gateway/SKILL.md
@@ -148,9 +148,11 @@ See [hookdeck-event-gateway-webhooks](https://github.com/hookdeck/webhook-skills
 
 For full Event Gateway product skills (connections, monitoring, API):
 
-> Coming soon: `npx skills add hookdeck/skills`
->
-> In the meantime, see [Hookdeck documentation](https://hookdeck.com/docs) for complete setup guides, [API reference](https://hookdeck.com/docs/api), and [CLI reference](https://hookdeck.com/docs/cli).
+```bash
+npx skills add hookdeck/agent-skills --skill event-gateway
+```
+
+See [hookdeck/agent-skills](https://github.com/hookdeck/agent-skills) for the complete Event Gateway skill, or the [Hookdeck documentation](https://hookdeck.com/docs) for setup guides, [API reference](https://hookdeck.com/docs/api), and [CLI reference](https://hookdeck.com/docs/cli).
 
 ## Recommended: webhook-handler-patterns
 

diff --git a/skills/outpost/SKILL.md b/skills/outpost/SKILL.md
@@ -55,10 +55,11 @@ Run Outpost on your own infrastructure:
 
 For detailed Outpost skills:
 
-> Coming soon: `npx skills add hookdeck/skills`
->
-> In the meantime, see the [Outpost documentation](https://outpost.hookdeck.com/docs)
-> and the [GitHub repo](https://github.com/hookdeck/outpost).
+```bash
+npx skills add hookdeck/agent-skills --skill outpost
+```
+
+See [hookdeck/agent-skills](https://github.com/hookdeck/agent-skills) for the complete Outpost skill, the [Outpost documentation](https://outpost.hookdeck.com/docs), and the [GitHub repo](https://github.com/hookdeck/outpost).
 
 ## Resources