Skip to content

jacob-balslev/skill-graph / examples/projects/saas-stripe-postgres/skills/stripe-webhook-signature-verification

stripe-webhook-signature-verification

Verified

Use when validating incoming Stripe webhook requests in a Node.js or Next.js backend before processing any payment event. Verifies the `stripe-signature` header against `STRIPE_WEBHOOK_SECRET` using Stripe's HMAC-SHA256 scheme, and rejects replays older than 300 seconds. Do NOT use for general HTTP signature validation (use a generic crypto-signature skill), for processing the webhook payload after signature is confirmed (use payment-provider-router), or for Stripe API calls that are not webhook-driven.

Stripe Webhook Signature Verification

Concept of the skill

What it is: The security check that proves an incoming Stripe webhook was signed by Stripe before any payment logic runs. Mental model: The raw request body, signature header, and webhook secret form one verification tuple; change any part and the event is untrusted. Why it exists: Webhook routes are public endpoints that can trigger billing and fulfillment, so authenticity has to be established before routing. What it is NOT: It is not payment-event routing, general HTTP signature validation, or Stripe API usage outside webhook delivery. Adjacent concepts: HMAC verification, raw request bodies, replay tolerance, idempotency keys. One-line analogy: It is the seal check before opening the payment envelope. Common misconception: Parsing JSON first is harmless; transforming the raw bytes invalidates the signature comparison.

Coverage

  • The raw-body requirement — why stripe.webhooks.constructEvent() requires the unparsed Buffer from the request body, and how Next.js App Router routes expose it via request.arrayBuffer()
  • HMAC-SHA256 verification — how constructEvent(rawBody, signature, secret) reconstructs and compares the Stripe signature internally
  • Replay protection — the 300-second tolerance window Stripe checks against the t= timestamp embedded in the stripe-signature header; when to tighten it
  • Environment-specific secrets — STRIPE_WEBHOOK_SECRET for production vs whsec_... from the Stripe CLI --forward-to session in development; why they must never be swapped
  • Idempotency key pattern — recording the event.id in Postgres before processing so a retried delivery does not double-charge or double-fulfill

Philosophy of the skill

A webhook that skips signature verification is an unauthenticated public endpoint that can trigger payment processing. The verification step is load-bearing security, not a convenience check. Stripe's SDK makes verification a single call, but two failure modes are common in practice: the request body gets parsed (by a body-parser middleware) before the raw bytes reach the verification call, which silently corrupts the HMAC comparison; and the wrong webhook secret is loaded from environment variables, producing a 400 that is hard to distinguish from a replay rejection. Both failures look the same to the caller — a rejected webhook — and both are invisible until a real event is dropped.

Verification

  1. Confirm raw body access. In Next.js App Router: const rawBody = Buffer.from(await request.arrayBuffer()). Do NOT pass await request.json() or await request.text() — both transform the bytes.

  2. Retrieve and verify.

    import Stripe from "stripe";
    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
    
    const sig = request.headers.get("stripe-signature") ?? "";
    let event: Stripe.Event;
    try {
      event = stripe.webhooks.constructEvent(
        rawBody,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET!
      );
    } catch (err) {
      return Response.json({ error: "Signature verification failed" }, { status: 400 });
    }
    
  3. Check idempotency before processing.

    INSERT INTO webhook_events (event_id, processed_at)
    VALUES ($1, now())
    ON CONFLICT (event_id) DO NOTHING
    RETURNING event_id;
    

    If the RETURNING clause returns no rows, the event was already processed — return 200 immediately without re-running side effects.

  4. Route the verified event to payment-provider-router.

Failure Mode Reference

FailureSymptomFix
Body parsed before verification400 on every real Stripe eventUse arrayBuffer(), not json() or text()
Wrong webhook secret400 with "No signatures found matching the expected signature"Verify STRIPE_WEBHOOK_SECRET matches the endpoint in the Stripe dashboard
Replay attack400 with "Timestamp too old"Legitimate if tolerance is tight; check t= value in the stripe-signature header
Secret from wrong environmentEvents verify in dev but fail in productionUse per-environment secrets; never share between environments

Do NOT Use When

Use insteadWhen
payment-provider-routerYou have a verified event and need to decide which handler processes it
nextjs-server-action-validationYou are validating user-submitted form data, not a Stripe webhook
(a generic HTTP signature skill)You are verifying webhooks from a non-Stripe provider with a different signing scheme
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall