diff --git a/AGENTS.md b/AGENTS.md index f34ebbf..2947e9c 100644 --- 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 index 997ff13..48e17b8 100644 --- 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 index 32847a0..852126f 100644 --- 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 index 175fd82..e987e8b 100644 --- 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 index ada07bb..13a5b0f 100644 --- 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