CtrlK
BlogDocsLog inGet started
Tessl Logo

circle-webhooks

Receive and verify Circle Payments Network (CPN) v2 webhooks. Use when setting up Circle webhook handlers, debugging ECDSA signature verification (X-Circle-Signature, X-Circle-Key-Id), or handling notifications like cpn.payment.*, cpn.transaction.*, and cpn.rfi.*.

73

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

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

A well-constructed skill body: executable verification code with caching, precise Circle-specific deviations from typical webhook providers, a useful event-type table, and properly split one-level-deep references. The main weaknesses are cross-promotional padding (Related Skills, Attribution, Recommended sections), the absence of inline on-verification-failure guidance, and example links that do not resolve within the bundle.

Suggestions

Add a short explicit step for failed verification (e.g., return 401/403 and log the keyId and signature for debugging) so the handler workflow is complete without relying on the external webhook-handler-patterns skill.

Fix or remove the examples/express/, examples/nextjs/, and examples/fastapi/ links — these directories are not present in the bundle, so either include them or point to where they actually live.

Trim the Attribution, Recommended, and Related Skills sections to a few lines (or move them to a single reference file) to reduce padding that competes with the core verification and setup content.

DimensionReasoningScore

Conciseness

The core sections are lean — no explanation of what webhooks or ECDSA are, and every table row and code line earns its place ("The public key for a keyId is static — cache it by keyId to avoid an API call per event"). However, the "Attribution" block, the four-link "Recommended: webhook-handler-patterns" section, and the nine-link "Related Skills" list are cross-promotional padding that could be condensed. This fits the level-4 anchor (efficient with minor trimmable content) rather than level 5, where every token would earn its place.

4 / 5

Actionability

The verification section provides a complete, copy-paste-ready Node.js implementation including key caching, DER/SPKI parsing, raw-body verification, and failure handling, plus concrete env vars ("CIRCLE_API_BASE_URL=https://api.circle.com # sandbox: https://api-sandbox.circle.com") and a runnable command ("npx hookdeck-cli listen 3000 circle --path /webhooks/circle"). Specific examples cover the common cases, matching the level-5 anchor; the level-4 anchor would allow minor gaps, and none are present in the core guidance.

5 / 5

Workflow Clarity

The core sequence (fetch key by X-Circle-Key-Id → cache → verify over raw body) is unambiguous and embodied in executable code with the critical gotcha called out ("raw bytes, not parsed JSON"), and the HEAD-validation requirement is explicit. It falls short of level 5 because there is no explicit guidance on what to do when verification fails (e.g., what HTTP status to return or whether to replay), and the overall handler sequence is delegated to an external companion skill rather than summarized inline. This is not a destructive/batch operation, so no workflow cap applies.

4 / 5

Progressive Disclosure

The body is a genuine overview with well-signaled, one-level-deep references — "references/overview.md — Circle webhook concepts, notification types, status values, payloads" etc., and all three referenced files exist in the bundle. It falls short of level 5 because the links "[examples/express/](examples/express/), [examples/nextjs/](examples/nextjs/), [examples/fastapi/](examples/fastapi/)" point to directories that are not present in this bundle, and the "Recommended" section routes to external GitHub files rather than bundled material — minor organization gaps relative to the anchor requiring clean, easy navigation.

4 / 5

Total

17

/

20

Passed

Description

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

An exemplary description: concrete actions, provider-specific artifacts, and an explicit "Use when" clause covering setup, debugging, and event handling. Both the what and when are answered with precise trigger terms, and the scoping to CPN v2 keeps conflict risk minimal.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — "Receive and verify Circle Payments Network (CPN) v2 webhooks", "debugging ECDSA signature verification", "handling notifications" — anchored by exact artifacts ("X-Circle-Signature, X-Circle-Key-Id", "cpn.payment.*, cpn.transaction.*, and cpn.rfi.*"). Coverage is comprehensive for the skill's domain, matching the anchor for multiple specific concrete actions; it is above the level-4 anchor because there are no minor gaps — the actions, headers, and event families are all named explicitly.

5 / 5

Completeness

It explicitly answers both questions: the "what" is "Receive and verify Circle Payments Network (CPN) v2 webhooks" and the "when" is the explicit "Use when setting up Circle webhook handlers, debugging ECDSA signature verification..., or handling notifications like..." clause with concrete trigger phrases. This matches the level-5 anchor exactly and is above level 4, where the "when" would be less specific or concrete triggers absent.

5 / 5

Trigger Term Quality

Natural trigger phrases a user would actually say are all present: "setting up Circle webhook handlers", "debugging ECDSA signature verification", "signature verification failing" territory covered by header names, and the exact event strings ("cpn.payment.*", "cpn.rfi.*") a developer debugging would paste. This matches the comprehensive-coverage anchor including synonyms ("Circle Payments Network (CPN) v2", "webhooks", "notifications") and is above the level-4 anchor, which allows missing natural terms.

5 / 5

Distinctiveness Conflict Risk

The triggers are tightly scoped to Circle's CPN product ("Circle Payments Network (CPN) v2", Circle-specific headers and cpn.* event strings), giving it a clear niche with minimal overlap risk against generic webhook or other payment-provider skills. It is above the level-4 anchor ("minor overlap risk with closely related skills") because the header names and cpn.* strings are unique to this provider and would not fire for sibling skills like stripe-webhooks.

5 / 5

Total

20

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 3 missing

Warning

Total

15

/

16

Passed

Repository
hookdeck/webhook-skills
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.