Stripe-Webhook-Signaturprüfung fehlgeschlagen — finde heraus, warum

Deine Stripe-Signatur debuggen

Stripe ist standardmäßig ausgewählt. Der HMAC wird in deinem Browser mit WebCrypto berechnet — dein whsec_ verlässt den Tab nie.

Anatomie des Stripe-Signature-Headers

Jeder Stripe-Webhook kommt mit einem Header an, der so aussieht. Jedes kommagetrennte Feld hat eine Aufgabe:

Stripe-Signature: t=1614556800,
  v1=5257a869e7ecebeda32affa62cdca3fa51cad7414a563a8c6e3c4b41c2b7f2c8,
  v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

Der signierte String ist `${t}.${rawBody}` — nicht der Body allein. Vergisst du in einem selbstgebauten Verifier das Präfix t., scheitert jede Signatur, selbst mit dem richtigen Secret.

Die 6 Grundursachen, in der Reihenfolge, in der du sie prüfen solltest

Sortiert danach, wie oft sie der Übeltäter sind. Jede hat ein Merkmal, das sie von den anderen unterscheidet.

Der Rohbody-Fix, Framework für Framework

Ursache Nr. 1 ist fast immer diese: Dein Web-Framework hat das JSON gelesen, geparst und neu serialisiert, bevor constructEvent es zu sehen bekam. Neu serialisiertes JSON hat andere Leerzeichen, also passt der HMAC nicht mehr. So gibst du jedem Framework die unveränderten Bytes.

// Die Webhook-Route MUSS vor express.json() kommen
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];
    const event = stripe.webhooks.constructEvent(
      req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
    res.json({ received: true });
  }
);
app.use(express.json()); // alles andere

export async function POST(req: Request) {
  const body = await req.text();            // roh, unverändert
  const sig = req.headers.get('stripe-signature')!;
  const event = stripe.webhooks.constructEvent(
    body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );
  return Response.json({ received: true });
}

import { buffer } from 'micro';
export const config = { api: { bodyParser: false } };

export default async function handler(req, res) {
  const raw = await buffer(req);
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(
    raw, sig, process.env.STRIPE_WEBHOOK_SECRET
  );
  res.json({ received: true });
}

Füg die exakten Bytes in den Debugger oben ein: Passt die Signatur erst, wenn du einen abschließenden Zeilenumbruch oder ein neu kodiertes Feld entfernst, wurde der Body unterwegs verändert — nicht dein Secret.

Testmodus vs. Live-Modus: das Secret, das richtig aussieht, es aber nicht ist

Stripe gibt dir drei verschiedene whsec_-Werte, und man verwechselt sie leicht. Erstens das Secret des Test-Endpoints, das im Dashboard angezeigt wird, solange du im Testmodus bist. Zweitens das Secret des Live-Endpoints — ein separater Wert am selben Endpoint, auf Live umgeschaltet. Drittens das CLI-Secret, das stripe listen ausgibt, wieder ein anderes und nur für Events gültig, die diese Session weiterleitet. Alle drei erzeugen einen plausibel aussehenden HMAC, der Fehler ist also derselbe generische No signatures found — nichts sagt Modus-Verwechslung. Das Erkennungszeichen: Testzahlungen werden verifiziert, echte liefern 400. Die Lösung: Lies das Secret genau von dem Endpoint, im genau dem Modus, der den Traffic empfängt.

Das 5-Minuten-Replay-Fenster, das alle vergessen

constructEvent prüft nicht nur den HMAC — es lehnt jedes Event ab, dessen t=-Timestamp älter als 300 Sekunden ist, und wirft Timestamp outside the tolerance zone. Das trifft dich, wenn du ein erfasstes Event Stunden später erneut sendest oder die Uhr deines Servers abgedriftet ist. Die Signatur ist völlig gültig; es ist das Alter, das scheitert. Der Debugger oben zeigt das Alter des Timestamps, damit du ein veraltetes Replay von einer echten Signaturabweichung unterscheiden kannst. Brauchst du wirklich ein längeres Fenster, nimmt constructEvent ein viertes Argument tolerance in Sekunden — aber korrigiere zuerst die Uhr.

Dein Handler oder dein Secret? Erzeuge ein garantiert gültiges Event

Sagt der Debugger, dass das Secret stimmt, die Produktion aber trotzdem 400 liefert, liegt der Bug darin, wie dein Handler den Body liest. Grenze ihn ein: Unser Signer erzeugt eine von Stripe signierte Payload mit einem Secret, das du kontrollierst, sodass du ein garantiert gültiges Event direkt per POST an deinen lokalen Handler schicken kannst. Klappt es, ist dein Verifikationscode in Ordnung, und das Problem ist das Secret oder die Middleware. Scheitert es, verändert der Handler den Body — zurück zur Rohbody-Tabelle oben.

Diagnose-Checkliste

Geh diese Punkte der Reihe nach durch, wenn constructEvent das nächste Mal eine Exception wirft.

1. Füg das fehlschlagende whsec_, den Rohbody und Stripe-Signature in den Debugger oben ein — er nennt die Ursache, bevor du weiterliest.
2. Stell sicher, dass der Body, der bei constructEvent ankommt, der unveränderte Roh-String ist und kein geparstes und neu serialisiertes Objekt.
3. Kopiere das Signing-Secret direkt von der Seite des Endpoints im Dashboard — nicht aus stripe listen, nicht von einem anderen Endpoint.
4. Prüfe, dass du für Live-Traffic das Live-Secret und für Test-Traffic das Test-Secret verwendest.
5. Logge req.headers['stripe-signature'] und stell sicher, dass der Header vorhanden ist und nicht von einem Proxy abgeschnitten wurde.
6. Prüfe, dass der t=-Timestamp des Events nicht älter als 5 Minuten ist (veraltetes Replay oder Uhrendrift).

Das echte fehlschlagende Event erfassen und erneut abspielen

Kommst du immer noch nicht weiter? Richte Stripe auf ein Webhook-Toolkit-Relay oder eine Capture-URL, fang genau den Request ab, der scheitert, und inspiziere Rohbody und Headers Byte für Byte — dann spiel ihn so oft gegen deinen Handler ab, wie du willst, ohne auf ein weiteres Live-Event zu warten.

Häufige Fragen