Read this article in English →
security · · · Streatix

Stripe-Webhook-Signatur prüfen: 11-Zeilen-Fix für KI-Code

KI-Tools liefern Stripe-Webhooks ohne Signaturprüfung. Wie die Fälschung abläuft, warum constructEvent den Raw Body braucht, und der 11-Zeilen-Fix.

Wer Lovable, Bolt, Cursor oder ein anderes aktuelles Modell nach einem Stripe-Webhook-Handler fragt, bekommt einen Handler, der den Request-Body liest, dessen Inhalt glaubt und in die Datenbank schreibt. Die Stripe-Webhook-Signatur prüft er nicht. Wir nennen das den Unsigned-Webhook-Default. Er taucht in fast jedem KI-generierten Handler auf, den wir bisher gesehen haben, und wir haben ihn in Referenz-Apps mit jedem dieser Tools reproduziert. Wer /api/stripe/webhook erreicht, markiert mit einem einzigen HTTP-Request und ohne Secret eine Bestellung als bezahlt oder stuft ein Konto hoch. Die Stripe-Dokumentation fordert die Signaturprüfung ausdrücklich. Das Modell liefert trotzdem diesen Code, solange der Prompt nicht danach fragt. Die Lösung sind constructEvent, der Raw Body und 11 Zeilen im Handler.

Der generierte Handler vertraut dem Body

Der Handler ruft request.json() auf und aktualisiert auf dieser Basis die Datenbank. Nichts prüft, ob der Request von Stripe stammt. Das hier generiert Lovable auf den Prompt „handle Stripe webhook“. Bolt und Cursor liefern beim selben Prompt dasselbe, bis auf den einen oder anderen Kommentar:

// app/api/stripe/webhook/route.ts

import { NextResponse } from 'next/server'
import { createClient } from '@/lib/supabase/server'

export async function POST(request: Request) {
  const event = await request.json()

  const supabase = createClient()

  if (event.type === 'checkout.session.completed') {
    await supabase
      .from('orders')
      .update({ status: 'paid', paid_at: new Date().toISOString() })
      .eq('stripe_session_id', event.data.object.id)
  }

  if (event.type === 'customer.subscription.created') {
    await supabase
      .from('users')
      .update({ plan: 'pro', subscription_active: true })
      .eq('stripe_customer_id', event.data.object.customer)
  }

  return NextResponse.json({ received: true })
}

Der Handler:

  1. Akzeptiert jeden POST-Request.
  2. Parst den Body als JSON.
  3. Aktualisiert die orders/users-Tabellen nach dem, was im JSON steht.

Keine Signaturprüfung, kein Shared Secret, keine Prüfung des Ursprungs. Wer die URL kennt, kann eine Bestellung auf paid setzen oder einen Nutzer in den pro-Plan heben.

Für den Exploit reicht ein curl-Befehl

Registrieren Sie ein kostenloses Konto und notieren Sie Ihre stripe_customer_id (oft auf der eigenen Profilseite sichtbar). Damit haben Sie ein Konto zum Hochstufen. Jede andere Kunden-ID, die Sie kennen, funktioniert genauso:

curl -X POST https://yourapp.com/api/stripe/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customer.subscription.created",
    "data": {
      "object": {
        "customer": "cus_THE_VICTIMS_ID"
      }
    }
  }'

Der Handler antwortet mit 200 OK. Der Kunde aus dem Payload hat nun ein pro-Abonnement, das niemand bezahlt hat. Tauscht man den Typ gegen checkout.session.completed und setzt eine Session-ID in data.object.id, wird diese offene Bestellung als bezahlt markiert, ohne dass Geld fließt.

Wir haben das in Referenz-Apps mit jedem dieser Tools reproduziert. Derselbe Handler, dieselbe Lücke, jedes Mal.

Das Prompt-Boundary-Problem erklärt, warum die Prüfung fehlt

Die Stripe-Dokumentation verlangt die Signaturprüfung ausdrücklich, eine Lücke in der Doku ist das also nicht. Es ist ein Prompt-Boundary-Problem in der Art, wie KI-Tools Code erzeugen.

Lautet der Prompt „build a Stripe webhook handler that marks orders as paid“, baut das Modell genau das. Der Prompt sagt nie prüfen, ob der Request wirklich von Stripe stammt, weil kein Gründer daran denkt, das hinzuschreiben. Und das Modell optimiert darauf, dass der Prompt funktioniert, nicht darauf, dass das Ergebnis in Produktion sicher ist.

Dieselbe Ursache sehen Sie überall in KI-generiertem Code. Der Happy Path wird gebaut, der Angriffspfad ignoriert: keine Negativtests, kein „Was, wenn ein Angreifer das schickt?“, keine Frage, ob man dem Request überhaupt trauen kann.

Manchmal lässt sich das abfangen, indem Sie „and verify the webhook signature“ an den Prompt hängen. Selbst dann sieht die erzeugte Prüfung in unseren Audits oft richtig aus und ist es nicht. Der übliche Fehler ist der geparste Body statt des Raw Body, und dann wird jedes echte Event abgelehnt.

Stripe-Webhook-Signatur prüfen: 11 Zeilen genügen

Stripes eigenes Next.js-Beispiel hat dieselbe Form: Body mit request.text() lesen, an constructEvent übergeben, 400 zurückgeben, falls das eine Exception wirft.

// app/api/stripe/webhook/route.ts

import { NextResponse } from 'next/server'
import Stripe from 'stripe'
import { createClient } from '@/lib/supabase/server'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!

export async function POST(request: Request) {
  const body = await request.text()                          // raw body, not JSON
  const signature = request.headers.get('stripe-signature')

  if (!signature) {
    return NextResponse.json({ error: 'Missing signature' }, { status: 400 })
  }

  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
  } catch (err) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }

  const supabase = createClient()

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session
    await supabase
      .from('orders')
      .update({ status: 'paid', paid_at: new Date().toISOString() })
      .eq('stripe_session_id', session.id)
  }

  if (event.type === 'customer.subscription.created') {
    const sub = event.data.object as Stripe.Subscription
    await supabase
      .from('users')
      .update({ plan: 'pro', subscription_active: true })
      .eq('stripe_customer_id', sub.customer as string)
  }

  return NextResponse.json({ received: true })
}

Drei Dinge haben sich geändert:

  1. Der Raw Body wird gelesen, nicht das geparste JSON. stripe.webhooks.constructEvent bildet den Hash über die Bytes des Bodys, und neu serialisiertes JSON reproduziert diese Bytes nicht. Mit der Ausgabe von request.json() schlägt die Prüfung bei jedem echten Event fehl.
  2. Der stripe-signature-Header wird geprüft. Fehlt er, wird der Request abgelehnt.
  3. constructEvent wird mit dem Webhook-Secret aufgerufen. Das ist die eigentliche Prüfung. Die Methode wirft einen Fehler, wenn die Signatur falsch ist, der Timestamp zu alt ist (Replay-Schutz) oder der Body nicht passt.

Außerdem brauchen Sie STRIPE_WEBHOOK_SECRET in den Umgebungsvariablen. Öffnen Sie im Stripe-Dashboard den Endpoint unter Workbench > Webhooks und klicken Sie auf Reveal secret (in der deutschen Oberfläche Geheimnis anzeigen). Der Wert beginnt mit whsec_.

constructEvent prüft einen HMAC über den Raw Body und einen Timestamp

Der Stripe-Signature-Header ist keine Blackbox. Er enthält einen Timestamp und eine oder mehrere Signaturen:

Stripe-Signature: t=1737936000,v1=5257a869e7...3b5f

constructEvent liest t und v1 aus, berechnet die Signatur selbst als HMAC-SHA256(secret = whsec_..., message = "{t}.{rawBody}") und vergleicht sie in konstanter Zeit mit v1, sodass ein falscher Versuch über das Timing nichts verrät. Zwei Bedingungen müssen gelten, sonst wirft die Methode einen Fehler:

  • Der neu berechnete HMAC entspricht v1. Deshalb zählt der Raw Body. Der HMAC läuft über exakt die Bytes, die Stripe signiert hat. Parsen und erneutes Serialisieren entfernt Whitespace und kann Schlüssel umsortieren, die Bytes stimmen dann nicht mehr, auch wenn das JSON inhaltlich gleich ist.
  • t liegt im Toleranzfenster, in stripe-node standardmäßig 300 Sekunden. Das ist der Replay-Schutz: Ein mitgeschnittener Request, der später erneut gesendet wird, scheitert nach fünf Minuten, ob die Signatur gültig ist oder nicht.

Wenn legitime Events in Produktion plötzlich fehlschlagen, prüfen Sie zuerst das Secret. Ein falsches whsec_ lässt jedes Event gleich scheitern, und Stripe nennt das falsche Secret als häufigste Ursache. Das Secret aus stripe listen ist nicht das Ihres Dashboard-Endpoints, so landet man leicht beim falschen.

Zwei Negativtests, die KI nicht schreibt, belegen den Fix

Zwei Tests. Beide negativ:

# 1. Unsigned request should return 400
curl -X POST https://yourapp.com/api/stripe/webhook \
  -H "Content-Type: application/json" \
  -d '{"type":"customer.subscription.created"}'
# Expect: 400 Missing signature

# 2. Forged signature should return 400
curl -X POST https://yourapp.com/api/stripe/webhook \
  -H "Content-Type: application/json" \
  -H "stripe-signature: t=1234567890,v1=deadbeef" \
  -d '{"type":"customer.subscription.created"}'
# Expect: 400 Invalid signature

Antwortet einer davon mit 200, ist Ihr Fix nicht korrekt deployt.

Für den Positivtest nutzen Sie stripe trigger aus der Stripe CLI. Das erzeugt korrekt signierte Test-Events, sofern Ihr lokales STRIPE_WEBHOOK_SECRET das Secret ist, das stripe listen ausgibt:

stripe listen --forward-to localhost:3000/api/stripe/webhook
stripe trigger customer.subscription.created

Die Signaturprüfung schützt nicht vor legitimen Events

Die Signaturprüfung stoppt gefälschte Stripe-Events. Sie verhindert nicht, dass legitime Events Ihre App durcheinanderbringen. Laut Stripe können Endpoints dasselbe Event mehrfach erhalten, und die Reihenfolge der Zustellung ist nicht garantiert. Sie können also ein echtes customer.subscription.deleted doppelt bekommen oder ein checkout.session.completed für eine Session, die Ihre Datenbank nicht kennt. Das braucht Idempotenz, Retry-Sicherheit und eine Strategie für die Event-Reihenfolge, und nichts davon löst dieser Fix. In unseren Audits führen wir das als eigene Findings.

Zwei Dinge liegen außerhalb dieses Artikels. Stripe empfiehlt zusätzlich, Webhook-Requests nur von seinen veröffentlichten IP-Adressen anzunehmen. Und für neue Integrationen rät Stripe inzwischen zu Thin Events, geprüft mit parseEventNotification(). constructEvent ist der Aufruf für die hier gezeigten Snapshot-Events.

KI-Tools schreiben den Handler, nicht das Threat Model

Jeder von außen erreichbare Endpunkt Ihrer App muss zwei Fragen beantworten:

  1. Wer darf das aufrufen? (Authentifizierung)
  2. Kann ein Aufrufer seine Identität fälschen? (Signatur- oder Origin-Prüfung)

Stehen die Antworten nicht irgendwo in Ihrem Code, beantwortet sie ein Angreifer.

Wenn Sie das für Ihre eigene App wollen

Dreißigminütiges Audit, kostenlos. Wir rufen dieselben Endpunkte per curl auf und lesen dieselben Dateien. Liste in Ihrem Postfach binnen achtundvierzig Stunden.

Kostenloses Audit buchen