Webhook Signature Verifier

What this skill does

Audits webhook receivers for missing or weak signature verification (e.g., string equality on HMAC, no timestamp tolerance, no replay protection) and proposes a hardened implementation per provider.

Inputs

• repo_dir: project root.
• provider: stripe, github, slack, twilio, custom.
• route_glob: where webhook handlers live (e.g., src/routes/webhooks/**).

Steps

1. Locate webhook handlers: for provider != custom, look for known import patterns (from 'stripe' -> Stripe; crypto.createHmac near X-Hub-Signature -> GitHub).
2. For each handler, statically analyze:
   • Is signature verification present? Pattern: crypto.createHmac or provider-SDK call (stripe.webhooks.constructEvent).
   • Is the comparison constant-time? Look for crypto.timingSafeEqual (Node) or hmac.compare_digest (Python). Plain === or == is a vulnerability.
   • Is the request body the raw body (not JSON-parsed)? bodyParser.json() consumes the buffer, so signature must be computed before parsing.
   • Is there a timestamp tolerance check? Stripe expects Stripe-Signature to include t=; verify a clock skew window (default 5 min).
   • Is replay-protected via a nonce/event-id store?
3. For each missing safeguard, emit a finding with file:line and severity (critical for missing-verification, high for non-constant-time, medium for missing-timestamp).
4. Suggest a per-provider hardened snippet (e.g., for Stripe: stripe.webhooks.constructEvent(rawBody, signatureHeader, secret, tolerance: 300)).
5. For custom providers, output a generic HMAC verifier template with constant-time compare and timestamp window.
6. Recommend infra-level moves: secret stored in env or KMS, never in code; separate secret per environment; rotation procedure.
7. Emit a markdown report.

Output

webhook-audit.md with: per-handler findings, hardened code suggestions, secret-management checklist. Plus a per-handler patch file. Exit 1 if any handler lacks any verification.

Verification

Deploy the hardened handler, send a request with an invalid signature, and confirm 401 is returned. Send a request with a valid signature but a stale timestamp (over the tolerance) and confirm rejection. Use the provider's CLI (e.g., stripe trigger) to send a real signed event and confirm 2xx. Add a test case using a fixture-signed payload so future refactors don't regress.

Edge cases

• Some frameworks consume the body by default (Express's body-parser): show the path-specific raw-body capture (express.raw({ type: 'application/json' })).
• Providers using non-HMAC signatures (e.g., Ed25519 via JWK): adapt the suggestion accordingly.
• Multi-tenant apps with one secret per tenant: lookup must be by tenant id; verify the lookup happens before verification, not after.
• Internal webhooks behind a private network: still verify; trust-on-network is brittle.