CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

paddle-webhooks

Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics, and local testing.

1.08x
Quality

81%

Does it follow best practices?

Impact

100%

1.08x

1 of 3 eval scenarios. Add 2 more for a full score.

SecuritybySnyk

Low

Low-risk findings worth noting

The canonical home for this skill is paddle-webhooks in PaddleHQ/paddle-agent-skills

SKILL.md
Quality
Evals
Security

Quality

Content

77%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.

An exceptionally actionable, well-sequenced integration guide whose validation section is a model feedback loop; its main costs are a ~360-line single-file body that inlines generic Paddle MCP/CLI conventions instead of factoring them into shared references, and a signature/status argument repeated three times. Tightening the repetition and moving the tool-convention digressions to reference files would raise both conciseness and progressive disclosure.

Suggestions

Move the generic Paddle MCP conventions and Paddle CLI conventions blockquotes into shared reference files (e.g. references/paddle-mcp.md and references/paddle-cli.md) and keep only a one-line pointer, since they apply to all Paddle skills, not just webhooks.

State the "one non-2xx for the whole catch because unmarshal errors are indistinguishable" argument once (Step 3) and have the pitfalls entry reference it instead of re-arguing it.

Trim repetition of simulator behavior (one attempt, no notification logs, replay via run events) between the Local testing section and the Verify section.

DimensionReasoningScore

Conciseness

The body is dense with genuinely non-obvious operational facts (retry budgets, 90-day replay window, 5-second timeout, destination-per-secret), but the "one non-2xx for the whole catch / 401 and 500 are equally safe" argument is repeated three times (the code comment, the Step 3 prose paragraph, and the first two pitfalls), and the verify section restates simulator facts again. Mostly efficient with unnecessary repetition that could be tightened — anchor 3, not 4, because the repetition is substantive padding rather than a minor instance.

3 / 5

Actionability

The main path is fully executable and copy-paste ready: complete SDK helper, complete route handler with pre-validation, event router with typed narrowing, an atomic guarded-UPSERT SQL statement, concrete ngrok/paddle CLI commands, and MCP execute snippets. Only deliberately-justified TODO placeholders and a user-defined db import are left abstract, matching the anchor-5 example of covering common cases with specific code.

5 / 5

Workflow Clarity

Steps 1–6 are clearly sequenced (create destination → SDK helper → route handler → routing → idempotency → queueing), and the dedicated "Verify the integration" section provides explicit validation checkpoints with a genuine feedback loop: tamper the secret, confirm non-2xx in the simulation run, restore, replay, and confirm success. This matches the anchor-5 example of explicit validation steps with error-recovery loops rather than the anchor-4 case, which would have a missing checkpoint.

5 / 5

Progressive Disclosure

Sections are well organized and the related-skills/docs links are clear, but there are no bundle files at all, and two long blockquotes on Paddle MCP conventions and Paddle CLI conventions are generic to all Paddle work rather than webhook-specific — content that clearly belongs in shared reference files is inlined. This matches anchor 3 ("content that should be separate is inline") rather than 2, because the inlined material is digressive rather than a monolithic wall, and rather than 4, because the digressions are substantial, not minor gaps.

3 / 5

Total

16

/

20

Passed

Description

75%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 specific, action-oriented, and highly distinctive within the Paddle/Next.js niche, but it omits any explicit 'Use when...' trigger clause, which caps its completeness at 3 and slightly weakens trigger-term coverage. Adding a when-to-use clause with natural phrases would lift it to top-tier.

Suggestions

Append an explicit trigger clause, e.g. "Use when building the server-side endpoint that receives Paddle webhook events or when the user mentions Paddle webhooks, notification destinations, or webhook signature verification."

Include a natural-phrase synonym such as "webhook endpoint" or "webhook handler" alongside "Route Handler" to broaden trigger-term coverage.

Soften technical phrasing like "retry semantics" toward wording a user would naturally say (e.g. "handle Paddle's retries").

DimensionReasoningScore

Specificity

"Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics, and local testing" lists multiple specific concrete actions (verify, signature verification, idempotency, retry semantics, local testing) scoped to a named stack, matching the comprehensive-coverage anchor. It is not a 4 because coverage of the skill's capabilities is complete with no notable gaps.

5 / 5

Completeness

The 'what' is clear (receive and verify Paddle webhooks with signature verification, idempotency, retry handling, and local testing) but there is no 'Use when...' clause or equivalent explicit trigger guidance, capping completeness at 3 per the judging guidelines. It is not a 4 because 'when' is only weakly implied by the domain naming, not stated.

3 / 5

Trigger Term Quality

Natural user phrases like "Paddle webhooks", "verify", and "Next.js Route Handler" are present, but common variations such as "webhook endpoint" or "webhook handler" are missing and terms like "retry semantics" lean technical. Good coverage with a few natural terms absent, matching anchor 4 rather than the comprehensive-synonyms anchor 5.

4 / 5

Distinctiveness Conflict Risk

The Paddle + Next.js Route Handler webhook niche is highly specific with distinct triggers, so conflict risk with other skills (even other Paddle skills like checkout-web or subscription-sync) is minimal. Matches the clear-niche anchor 5 rather than 4, which would require some overlap risk with closely related skills.

5 / 5

Total

17

/

20

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

Validation for skill structure

No warnings or errors.

Repository

PaddleHQ/paddle-agent-skills

Path

providers/codex/plugin/skills/webhooks/SKILL.md

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.