When I ask my AI coding agent to set up webhooks from a new API (Stripe, Shopify, GitHub, whatever), the code it generates often looks fine until I run it. Then I hit signature verification failures, wrong raw body handling, or idempotency bugs that process the same event twice. Sound familiar?
I created webhook-skills to fix that. They're agent skills for webhooks: an open-source collection of provider- and framework-specific instructions and runnable examples that AI coding agents can load so they implement webhooks correctly the first time. In this guide I'll walk through how to use them, what's in them, and how you can contribute or request skills that are missing.
Why Agents Get Webhooks Wrong
At Hookdeck we process billions of webhooks a week, and we've seen every failure mode: signature mismatches from body parsing middleware, framework-specific gotchas that only show up in production, and so on. AI agents struggle with the same things. Their training data goes stale quickly. API versions change, security practices evolve, and the details that matter (raw body handling, middleware order, encoding) aren't in the model.
Research from PostHog on LLM code generation backs this up: the most reliable way to get correct code isn't the model's general knowledge; it's giving it specific, known-working examples to reference. Webhook skills are built to fill that gap.
How Webhook Skills Fix It
Webhook-skills is built on the Agent Skills specification, an open standard for packaging knowledge that agents can consume. In practice that means:
- Runnable examples: complete, minimal apps the agent can reference and adapt, not just snippets.
- Provider-specific guidance: Stripe's raw body requirement, Shopify's HMAC encoding, and other gotchas we see trip up developers.
- Framework-aware implementations: how Next.js, Express, and FastAPI handle request bodies, middleware order, and async patterns.
- Staged workflows: verify signature first, parse payload second, handle idempotently third.
When I ask my agent to "add Stripe webhooks to my Next.js app," it doesn't hallucinate a generic handler. It has the exact patterns for App Router body handling, preserving the raw body before verification, and pulling the webhook secret from env with the right naming. That's the difference.
How to Use Them
Install the skills
I use npx skills to add webhook-skills to my project. First I list what's available, then I install the skills I need:
# List available skills
npx skills add hookdeck/webhook-skills --list
# Install best-practice patterns (verify → parse → handle idempotently)
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns
# Install specific provider skills
npx skills add hookdeck/webhook-skills --skill stripe-webhooks
npx skills add hookdeck/webhook-skills --skill shopify-webhooks
I usually install webhook-handler-patterns plus the provider skill for whichever API I'm integrating. That gives my agent both the general flow and the provider-specific details.
How to prompt
Once the skills are installed, I prompt naturally. For example:
- "Add Shopify webhook handling to my Express app."
- "Set up Stripe webhooks in my Next.js app."
- "Implement GitHub webhook verification in my FastAPI service."
The agent has the patterns; I don't need to spell out raw body or signature verification. It already knows.
Local testing (optional)
When I'm testing webhooks locally, I use the Hookdeck CLI. It gives me a public URL that tunnels to my local server and a UI to inspect and replay requests:
npm i -g hookdeck-cli
# or: brew install hookdeck/hookdeck/hookdeck
hookdeck listen 3000 --path /webhooks/stripe
No account required to get started. The skills work with or without Hookdeck; they're just complementary when you want to receive real webhooks on localhost.
What's Available (and What's Missing)
Right now webhook-skills covers the providers and frameworks we see most often:
Providers: Stripe, Shopify, GitHub, OpenAI, Resend, Paddle, ElevenLabs, Chargebee, and more.
Frameworks: Next.js, Express, and FastAPI.
Each provider skill includes signature verification, event handling guidance, common failure modes, and testing tips for local dev. Coverage isn't complete yet. If you need a provider we don't have or you want to contribute, see the next section.
How to Contribute and Ask for Skills
Request a skill: If you're integrating a provider we don't support yet, open an issue on GitHub with a title like "Skill request: [Provider] webhooks". Describe the provider and your framework if relevant. I use these to prioritize what to add next.
Contribute a skill: If you've built a webhook integration you're proud of, PRs for new providers or frameworks are welcome. The repo is hookdeck/webhook-skills. Check the existing skills for structure and open a PR.
API and platform maintainers: If you maintain a webhook-producing API and want AI coding agents to implement your webhooks correctly out of the box, I'd love a skill from you. Open an issue or PR and we can align on format and content.
Give It a Shot
If you've ever lost an afternoon to webhook signature verification or body parsing, try webhook-skills the next time you're wiring up an integration. Install the skills, prompt your agent, and you might find it finally does what you meant.
Links:
- webhook-skills on GitHub
- Hookdeck CLI (optional, for local webhook testing)
Have feedback or want to request or contribute a skill? Open an issue.
Top comments (0)