A route that reads X-Shopify-Topic and ships the order, but never checks X-Shopify-Hmac-Sha256, ships orders for anyone who finds the URL. So does an HMAC computed over JSON.stringify(req.body), a twilio.webhook({ validate: false }) left over from testing, or a check that returns true when the signature header is missing. This skill finds those and seven other webhook mistakes before the endpoint goes live, and tells you how to fix each one.

Your agent runs a scanner on your webhook code in JavaScript and TypeScript (Express, Next.js, NestJS, Hono, Koa, Fastify), Python (Flask, FastAPI, Django, AWS Lambda), PHP (Laravel), Ruby (Rails, Sinatra) and Go. It finds each route and treats a POST route as a GitHub, GitLab, Shopify, Twilio, Paddle, Lemon Squeezy, Polar, Svix, Clerk, Resend, SendGrid, Mailgun, Square, Razorpay or Coinbase receiver when it reads that provider's headers or event payload. It checks each route on its own and knows each provider's verification calls (octokit verify, authenticate.webhook, twilio.webhook(), paddle.webhooks.unmarshal, validateEvent, verifyWebhook, Svix Webhook.verify and more), so verified routes, and routes covered by a verifying middleware, decorator or helper in another scanned file (Express app.use, Go handler wrappers, Next.js middleware, Rails before_action and Rack::TwilioWebhookAuthentication), are not reported. It skips comments and test files and never runs your code. It returns BLOCK, REVIEW, or NOT FLAGGED, with the file, line, reason, and a safer approach. Secrets are never printed.

What it checks

BLOCK (fix before shipping)

• W01: POST routes that read a provider's webhook headers or payload with no signature verification
• W02: webhook signing secrets, provider keys and GitLab tokens written in the code
• W03: verification switched off or failing open (validate: false, octokit receive(), letting the request through when the signature or secret is missing, rejecting only when a signature is present, or going on after a failed verify)

REVIEW (check before release)

• W11: signatures compared with ==, ===, strcmp or bytes.Equal instead of a constant-time comparison
• W12: HMACs computed over re-serialized JSON instead of the raw request body
• W13: hand-written checks of timestamped signatures with no time window (replay)
• W14: order and payment events handled with no event-id or duplicate check
• W15: GitHub's legacy SHA-1 X-Hub-Signature or Square's legacy signature header
• W16: webhook secrets read from the environment with a hard-coded fallback value
• W17: verification that an environment setting or a SKIP_ or DISABLE_ flag can turn off

What's included

• The scanner (Python 3.9+, standard library only)
• A rules guide with the reason, safer approach and provider documentation link for each rule
• A risky and a safe example project, and the real report the scanner produces on the risky one

Limits

It reads code as written: verification done by an API gateway, a proxy or code outside the scanned folder is not seen, and values built across several files are not followed. A route that only names a provider in its path is not treated as a webhook receiver. Stripe webhooks are not covered. NOT FLAGGED is not a guarantee.

Contents

One ZIP file with 19 files: SKILL.md, the scanner in scripts/ (6 Python files), references/rules.md (every rule with its reason and safer approach), and examples/ (10 example files plus report.md, the real scanner output on the risky example).

How to use: This is an agent skill: a folder with a SKILL.md file and Python scripts that an AI coding agent such as Claude Code, Cursor, or Codex CLI can run. Unzip it into your agent's skills folder (for Claude Code: ~/.claude/skills/), then ask your agent to check your project. The scripts also run on their own with Python 3.9 or newer, with nothing to install. They read your files only: no network access, and nothing is sent anywhere.