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

89%

Does it follow best practices?

Impact

89%

1.12x

Average score across 3 eval scenarios

Securityby

Low

Low-risk findings worth noting

Quality

Content

86%Weight 40%Scale 1-5

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

The body is an efficient, well-organized overview that defers detail to a real, clearly-labeled reference bundle with a solid inline quick reference. Its main gap is the absence of executable code examples and explicit error-recovery feedback loops in the workflow.

Suggestions

Add one short copy-paste-ready handler snippet (e.g., an Express raw-body verify→parse→idempotency skeleton) to lift actionability toward fully executable guidance.

Make the retry feedback loop explicit in the workflow — note that returning 5xx triggers provider retry-with-backoff, mirroring the response-code table.

Add an explicit validation checkpoint in the handler sequence (e.g., 'only proceed to processing once signature verification passes') to strengthen workflow clarity for batch/idempotent delivery.

Dimension	Reasoning	Score
Conciseness	The body is lean — terse 'When to Use' bullets, a compact resource index, a response-code table, and short checklists — with no padding explaining what webhooks or frameworks are; every line earns its place, matching the anchor-5 example.	5 / 5
Actionability	Provides concrete, executable guidance (specific response codes with provider behavior, an explicit ordered handler sequence, a 5-step idempotency checklist) but contains no copy-paste-ready code, so it falls short of anchor 5's 'fully executable code covering common cases' while clearly exceeding anchor 3's pseudocode level.	4 / 5
Workflow Clarity	The core verify→parse→idempotency sequence is clearly numbered with bolded steps, and the idempotency checklist acts as an explicit validation gate, but error-recovery feedback loops (e.g., 'on failure return 5xx to trigger retry') remain implicit rather than explicit, capping it below 5.	4 / 5
Progressive Disclosure	SKILL.md is a clear overview with a Resources section pointing to 7 one-level-deep reference files (all verified to exist), clearly signaled and grouped by topic, with a digestible Quick Reference inline and details appropriately deferred to references.	5 / 5
	Total	18 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concise, specific, and well-structured, explicitly pairing a clear capability statement with a detailed 'Use when' trigger clause. Its only mild weakness is slightly less exhaustive synonym/extension coverage in the trigger terms.

Dimension	Reasoning	Score
Specificity	Names the webhook-handler domain and enumerates multiple concrete capability areas — handler sequence (verify/parse/idempotency), idempotency, error handling, retry logic, and framework-specific issues — giving comprehensive coverage rather than the minor gaps allowed at 4.	5 / 5
Completeness	Explicitly answers both what ('Best practices for webhook handlers') and when ('Use when implementing the handler sequence... idempotency, error handling, retry logic, or framework-specific issues...'), with concrete enumerated trigger phrases matching the anchor-5 example; the 'Use when' clause is present so no cap applies.	5 / 5
Trigger Term Quality	Strong natural keywords ('webhook handlers', 'idempotency', 'error handling', 'retry logic', 'Express', 'Next.js', 'FastAPI') with an explicit 'Use when' trigger, but a few common synonyms (bare 'webhooks', 'signature verification') are absent, stopping short of anchor 5's comprehensive synonym coverage.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear, well-bounded niche (webhook handlers) with distinct triggers tied to specific frameworks and webhook-only concerns (idempotency, retry, signature ordering), presenting minimal overlap risk with unrelated skills.	5 / 5
	Total	19 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 3 deeper-than-1-level	Warning
referenced_paths_exist	Referenced path issues: 6 deeper-than-1-level	Warning

	Total	14 / 16 Passed

Repository: hookdeck/webhook-skills
Path: skills/webhook-handler-patterns/SKILL.md
Commit: daaf3db

Reviewed: 3 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.