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.

1.12x

Quality

78%

Does it follow best practices?

Impact

89%

1.12x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/webhook-handler-patterns/SKILL.md

Quality

Content

57%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill is well-organized as a hub document with clear progressive disclosure to reference files. Its main weakness is the lack of any concrete code examples in the SKILL.md itself—even a minimal snippet showing signature verification or idempotency check would significantly improve actionability. The Related Skills section is disproportionately long relative to the instructional content.

Suggestions

Add at least one concrete, executable code example in the Quick Reference section (e.g., a minimal Express webhook handler showing verify → parse → handle idempotently).

Trim the Related Skills section or move it to a separate file—10 external links consume significant tokens without adding instructional value.

Add explicit error recovery guidance in the handler sequence (e.g., 'If verification fails, log the attempt and return 401; do not parse or process the payload').

Dimension	Reasoning	Score
Conciseness	The Quick Reference section is efficient and well-structured, but the 'When to Use This Skill' section is somewhat redundant with the content itself, and the Related Skills section is very long with 10 external links that add bulk without much instructional value.	2 / 3
Actionability	The handler sequence and idempotency checklist provide clear steps, and the response codes table is useful. However, there are no concrete code examples—no executable snippets for signature verification, idempotency checks, or framework-specific patterns. All code-level guidance is deferred to reference files.	2 / 3
Workflow Clarity	The three-step handler sequence (verify → parse → handle idempotently) is clearly stated, and the idempotency checklist provides a reasonable workflow. However, there are no explicit validation checkpoints or error recovery feedback loops (e.g., what to do when verification fails beyond 'reject with 4xx').	2 / 3
Progressive Disclosure	Excellent structure with a concise overview, well-organized one-level-deep references to handler sequence, best practices, and framework-specific guides. Navigation is clear with descriptive link text and logical grouping.	3 / 3
	Total	9 / 12 Passed

Description

100%

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 strong skill description that clearly defines its scope around webhook handler best practices, includes an explicit 'Use when' clause with multiple specific trigger scenarios, and names concrete frameworks. The description is concise yet comprehensive, covering both the conceptual domain (idempotency, retry logic) and practical context (specific frameworks).

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'handler sequence (verify first, parse second, handle idempotently)', 'idempotency', 'error handling', 'retry logic', and 'framework-specific issues with Express, Next.js, or FastAPI'. These are concrete, actionable topics rather than vague abstractions.	3 / 3
Completeness	Clearly answers both 'what' (best practices for webhook handlers covering verification, parsing, idempotency, error handling, retry logic) and 'when' (explicit 'Use when' clause listing specific trigger scenarios including framework-specific issues).	3 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'webhook handlers', 'idempotency', 'error handling', 'retry logic', 'Express', 'Next.js', 'FastAPI', 'verify', 'parse'. These cover both conceptual terms and specific framework names users would mention.	3 / 3
Distinctiveness Conflict Risk	The combination of 'webhook handlers' with specific concerns like idempotency, handler sequence, and named frameworks (Express, Next.js, FastAPI) creates a clear niche that is unlikely to conflict with general error handling or generic web development skills.	3 / 3
	Total	12 / 12 Passed

Validation

100%

Warnings & errors only

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: da37fc7

Reviewed: 18 days ago

Table of Contents

Discovery Implementation Validation

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.