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

83%

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

SKILL.md
Quality
Evals
Security

Quality

Content

88%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 guide: complete executable code for every step, explicit validation with a tamper-and-recover feedback loop, and deep non-obvious Paddle delivery semantics throughout. The only weaknesses are moderate repetition of the status-code rationale and a monolithic single-file structure with some content (MCP/CLI conventions, parts of the pitfalls list) that could live in reference files.

DimensionReasoningScore

Conciseness

The body is dense with non-inferable Paddle facts ("Only 2xx within 5 seconds is 'delivered'", sandbox/live retry budgets, 5-second signature timestamp tolerance, GET /ips allowlisting) and assumes Claude's competence — no filler about what webhooks or HMAC are. It falls short of 5 because the same 401-vs-500 "one catch, one status" rationale is fully restated three times (Step 3 code comments, the prose paragraph after it, and the "Splitting the catch" pitfall), replay guidance is triplicated, and the two long MCP/CLI convention blockquotes are tangential digressions from webhook handling.

4 / 5

Actionability

Fully executable throughout: a complete route handler, the SDK helper with file path, a guarded UPSERT SQL statement with column types, the event-id ledger with CREATE TABLE plus a transactional code sample, exact `paddle notification-settings create` CLI invocations with JSON bodies, env-var setup, and ngrok commands. Copy-paste ready, and the common cases (sync work and non-idempotent side effects) each get a worked example.

5 / 5

Workflow Clarity

Six clearly sequenced steps (create destination → SDK helper → route handler → event routing → idempotency → queue heavy work) with a dedicated "Verify the integration" section containing explicit checkpoints, including a deliberate feedback loop: tamper with the secret, confirm the non-2xx and the failed delivery, restore the secret, replay, and confirm success. Common pitfalls add error-recovery guidance (missed events after downtime, clock skew, wrong secret).

5 / 5

Progressive Disclosure

No bundle files exist, so all content is in one ~360-line SKILL.md — with good structure: scannable section headers, sibling-skill pointers, and a Related docs list of external links. It stays at 4 rather than 5 because the file is well past the simple-skill threshold and includes separable inline material — the ~40 lines of generic Paddle MCP/CLI conventions and the long pitfalls section are candidates for reference files that would keep the core webhook workflow leaner.

4 / 5

Total

18

/

20

Passed

Description

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

A specific, well-scoped description that clearly states what the skill does with concrete, non-generic capability terms and excellent distinctiveness. Its one real weakness is the complete absence of a "when to use" trigger clause, which both caps completeness and leaves natural trigger phrases implicit.

Suggestions

Append an explicit trigger clause, e.g. ". Use when building the server-side endpoint that receives Paddle webhook events, verifying paddle-signature headers, or handling webhook retries and idempotency in a Next.js app."

Include one or two natural user-side synonyms such as "webhook endpoint" or "webhook handler" so the description matches how users phrase the request.

Optionally mention creating notification destinations and replaying missed events, which the body covers but the description omits, for fuller coverage of the skill's scope.

DimensionReasoningScore

Specificity

Names several concrete capabilities — "receive and verify Paddle webhooks", "signature verification, idempotency, retry semantics, and local testing" — each a specific, checkable action. It stays at 4 rather than 5 because body-covered capabilities (creating the notification destination, replaying missed notifications) are absent, leaving minor gaps in coverage.

4 / 5

Completeness

The "what" is explicit and concrete ("Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics"), but there is no "Use when…" clause or equivalent explicit trigger guidance; the "when" is only weakly implied by the Paddle/Next.js framing. Per the rubric's guideline, a missing explicit trigger clause caps completeness at 3.

3 / 5

Trigger Term Quality

Contains the natural phrases a user would say — "Paddle webhooks", "Next.js Route Handler", "signature verification", "idempotency", "local testing". A few natural synonyms users might use ("endpoint", "callback", "webhook handler") are missing, which keeps it just below comprehensive coverage.

4 / 5

Distinctiveness Conflict Risk

"Paddle webhooks in a Next.js Route Handler" carves out a clear niche with distinct triggers — the named vendor, framework, and artifact (webhook verification) make it unlikely to fire for the wrong skill (e.g., the sibling subscription-sync or checkout-web skills). No notable overlap risk is present.

5 / 5

Total

16

/

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

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.