webhook-handler-patterns
Best practices for webhook handlers. Use when implementing the handler sequence (verify first, parse second, handle idempotently), idempotency, error handling, retry logic, or framework-specific issues with Express, Next.js, or FastAPI.
89
87%
Does it follow best practices?
Impact
89%
1.12xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Quality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-crafted skill description with excellent trigger terms and completeness. It clearly identifies when to use the skill and covers relevant frameworks. The main weakness is that the capabilities are described more as topic areas ('best practices', 'error handling') rather than concrete actions Claude will perform.
Suggestions
Replace 'Best practices for' with specific actions like 'Implements webhook signature verification, idempotent event processing, and retry-safe error responses'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (webhook handlers) and lists several actions/concepts (verify, parse, handle idempotently, error handling, retry logic), but these are more like topic areas than concrete actions. It mentions frameworks but doesn't specify what concrete actions are performed with them. | 2 / 3 |
Completeness | Clearly answers both what (best practices for webhook handlers including verification, parsing, idempotency, error handling, retry logic) and when (explicit 'Use when' clause with specific trigger scenarios including framework-specific issues). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'webhook', 'idempotency', 'retry logic', 'error handling', plus specific framework names (Express, Next.js, FastAPI). These are terms developers naturally use when seeking webhook help. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with clear niche around webhook handlers specifically. The combination of 'webhook', 'idempotency', and the handler sequence pattern creates a unique fingerprint unlikely to conflict with general API or error handling skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill demonstrates excellent organization and progressive disclosure, serving as an effective overview that points to detailed reference materials. The content is concise and well-structured with clear workflows. The main weakness is the lack of executable code examples in the quick reference section, relying instead on abstract descriptions and checklists.
Suggestions
Add a minimal executable code example in the Quick Reference section showing the verify → parse → handle pattern in at least one framework
Include a concrete idempotency implementation snippet (e.g., database check pattern) rather than just the checklist
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, avoiding explanations of basic concepts Claude already knows. Every section serves a purpose with no padding or unnecessary context. | 3 / 3 |
Actionability | Provides a clear checklist and response code table, but lacks executable code examples. The handler sequence is described abstractly rather than with copy-paste ready implementations. | 2 / 3 |
Workflow Clarity | The three-step handler sequence (verify → parse → handle idempotently) is clearly numbered and sequenced. The idempotency checklist provides explicit steps with a logical order. | 3 / 3 |
Progressive Disclosure | Excellent structure with a quick reference overview and well-signaled one-level-deep references to detailed materials. Framework guides and best practices are clearly organized and easy to navigate. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- hookdeck/webhook-skills
- Commit
f8a4801
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.