Stripe-Webhook: „Signature verification failed“ beheben
Kurz gesagt: Meldet Ihr Shop oder Ihre Web-App „Webhook signature verification failed. No signatures found matching the expected signature for payload“, stimmt laut Stripe-Dokumentation (abgerufen November 2026) mindestens einer von drei Werten nicht: der unveränderte Anfrageinhalt, die Kopfzeile „Stripe-Signature“ oder das Endpunkt-Geheimnis. In der Praxis sind es fast immer zwei Ursachen: ein falsches Geheimnis, etwa das aus dem Testwerkzeug statt das aus dem Dashboard, oder ein Framework, das den Anfrageinhalt verändert, bevor Ihr Code ihn prüft. Beides lässt sich gezielt prüfen. Wichtig ist danach, die verpassten Ereignisse nachzuholen.
Warum Stripe Webhooks signiert
Stripe meldet Ihrem System über Webhooks, was passiert ist: eine Zahlung ist eingegangen, eine Zahlung ist fehlgeschlagen, ein Abo wurde verlängert. Damit niemand Ihrem Shop eine gefälschte Meldung „Zahlung erfolgreich“ unterschieben kann, unterschreibt Stripe jede Nachricht. Ihr Code prüft diese Unterschrift mit einem gemeinsamen Geheimnis. Schlägt die Prüfung fehl, verwirft Ihr System die Nachricht, und das ist richtig so.
Die Folgen eines dauerhaften Prüffehlers sind allerdings unangenehm: Bestellungen bleiben auf „wartet auf Zahlung“, obwohl das Geld da ist. Abos werden nicht freigeschaltet. Bestätigungsmails gehen nicht hinaus.
Ein Beispiel zur Veranschaulichung: Ein Online-Kursanbieter in Köln stellt seine Web-App auf eine neue Framework-Version um. Ab dem Update erhalten neue Teilnehmende nach der Zahlung keinen Zugang mehr. Im Protokoll steht bei jeder Stripe-Meldung derselbe Signaturfehler.
Die drei Werte, die stimmen müssen
Laut Stripe ruft Ihr Code eine Prüffunktion mit drei Werten auf:
| Wert | Was er ist | Typischer Fehler |
|---|---|---|
| Anfrageinhalt | Der rohe Text, den Stripe geschickt hat | Framework hat ihn schon umgewandelt |
| Signatur | Der Inhalt der Kopfzeile Stripe-Signature | Kopfzeile wird von einem Proxy entfernt oder umbenannt |
| Endpunkt-Geheimnis | Ein Wert, der mit whsec_ beginnt | Falsches Geheimnis hinterlegt |
Stripe empfiehlt, jeden Wert einmal zu protokollieren und zu vergleichen. Die Signatur sollte laut Dokumentation einem Muster wie „t=…,v1=…“ folgen.
Ursache 1: das falsche Geheimnis
Stripe nennt das falsche Endpunkt-Geheimnis als häufigste Ursache. Die Dokumentation unterscheidet ausdrücklich zwei Geheimnisse, die man nicht verwechseln darf:
- Das Geheimnis eines im Dashboard eingerichteten Endpunkts. Es lässt sich dort beim Endpunkt anzeigen.
- Das Geheimnis, das das Kommandozeilenwerkzeug beim Weiterleiten auf den eigenen Rechner ausgibt.
Beide beginnen mit „whsec_“ und sehen sich ähnlich. Wer beim Entwickeln mit dem Kommandozeilenwerkzeug gearbeitet hat und dieses Geheimnis in die Produktivkonfiguration übernimmt, bekommt in der Liveumgebung nur Fehler. Dasselbe gilt, wenn jemand einen Endpunkt im Dashboard löscht und neu anlegt: Der neue Endpunkt hat ein neues Geheimnis.
Prüfen Sie deshalb konkret, welches Geheimnis Ihr Server gerade verwendet, und vergleichen Sie es mit dem angezeigten Wert des Endpunkts, an den Stripe tatsächlich sendet. Achten Sie auch darauf, dass Test- und Livemodus unterschiedliche Endpunkte und damit unterschiedliche Geheimnisse haben können.
Ursache 2: der veränderte Anfrageinhalt
Laut Stripe muss der Anfrageinhalt exakt der UTF-8-Text sein, den Stripe gesendet hat, ohne jede Veränderung. Viele Frameworks lesen eingehende Anfragen automatisch als JSON ein. Dabei können sie laut Dokumentation Schlüssel umsortieren, Leerzeichen entfernen, den Text in ein Objekt umwandeln oder die Kodierung ändern. Schon ein fehlendes Leerzeichen macht die Signatur ungültig.
Stripe nennt dazu konkrete Beispiele:
- Bei Node.js mit Express muss die Webhook-Route vor der allgemeinen JSON-Verarbeitung stehen. Express arbeitet die Zwischenschritte der Reihe nach ab. Läuft die JSON-Verarbeitung zuerst, ist der rohe Text verloren.
- Bei bestimmten Next.js-Varianten muss die automatische Verarbeitung des Anfrageinhalts für diese Route abgeschaltet werden.
- Bei Cloud-Funktionen hinter einem API-Gateway braucht es eine Einstellung, die den rohen Inhalt weiterreicht.
Ein Framework-Update ist deshalb ein klassischer Auslöser. Wenn sich die Reihenfolge der Zwischenschritte oder das Standardverhalten ändert, funktioniert eine Route, die jahrelang lief, plötzlich nicht mehr.
Weitere Stolpersteine auf dem Weg
Zwischen Stripe und Ihrem Code liegen oft weitere Stationen: eine Firewall, ein Lastverteiler, ein Plugin, das Anfragen protokolliert. Jede davon kann den Inhalt oder die Kopfzeilen verändern. Wenn Geheimnis und Framework stimmen und es trotzdem scheitert, prüfen Sie, ob die Anfrage unterwegs umgeschrieben wird. Ein Testversand aus dem Dashboard an den Endpunkt hilft, das einzugrenzen.
Verpasste Ereignisse nachholen
Ist der Fehler behoben, bleibt die Frage, was mit den Meldungen aus der Zwischenzeit passiert. Laut Stripe versucht das System nicht zugestellte Ereignisse automatisch bis zu drei Tage lang erneut zuzustellen. Ging der Ausfall länger oder wollen Sie schneller aufholen, beschreibt Stripe einen manuellen Weg: Über die Ereignisliste der Schnittstelle lassen sich gezielt Ereignisse abrufen, deren Zustellung fehlgeschlagen ist. Stripe liefert dabei laut Dokumentation nur Ereignisse der letzten 30 Tage.
Beim Nachholen ist eine Regel entscheidend: Kein Ereignis darf doppelt verarbeitet werden. Stripe rät, jedes Ereignis vor der Verarbeitung als „in Arbeit“ zu markieren und danach als „erledigt“. So schadet es nicht, wenn Ihr Nachhol-Skript zweimal läuft oder Stripe parallel noch automatisch zustellt.
Wer im Betrieb was prüfen kann
Nicht jede Prüfung braucht einen Entwickler. Den ersten Teil kann auch jemand aus dem Büro übernehmen, der Zugang zum Stripe-Dashboard hat. Im Bereich für Webhooks sieht man beim jeweiligen Endpunkt, welche Zustellungen fehlgeschlagen sind, wann das begann und welchen Statuscode Ihr Server zurückgegeben hat. Fällt der Beginn mit einem Update, einem Hosting-Wechsel oder einer neuen Domain zusammen, ist das ein wertvoller Hinweis für die Technik. Notieren Sie außerdem, ob Test- und Livemodus gleichermaßen betroffen sind. Mit diesen Angaben kann Ihr Entwickler gezielt bei Geheimnis, Framework oder Proxy ansetzen, statt den ganzen Ablauf von vorne zu untersuchen.
Damit es nicht wieder passiert
- Protokollieren Sie fehlgeschlagene Signaturprüfungen mit Zeitpunkt und Endpunkt, aber niemals das Geheimnis selbst.
- Lassen Sie sich benachrichtigen, wenn mehrere Prüfungen hintereinander scheitern.
- Testen Sie nach jedem Framework-Update eine Zahlung im Testmodus bis zum Ende.
- Dokumentieren Sie, welches Geheimnis zu welchem Endpunkt und Modus gehört.
Häufige Fragen
Kann ich die Signaturprüfung vorübergehend abschalten?
Davon ist abzuraten. Ohne Prüfung könnte jeder Ihrem System eine gefälschte Zahlungsbestätigung schicken. Beheben Sie lieber die Ursache, Stripe stellt in der Zwischenzeit erneut zu.
Warum funktioniert es lokal, aber nicht auf dem Server?
Lokal nutzen Sie vermutlich das Geheimnis des Kommandozeilenwerkzeugs, auf dem Server ist ein anderer Endpunkt aktiv. Oder auf dem Server liegt ein Proxy dazwischen, der lokal fehlt.
Gehen Zahlungen verloren, wenn die Prüfung scheitert?
Das Geld nicht, nur die Meldung an Ihr System. Die Zahlung ist bei Stripe verbucht. Ihre Bestellungen müssen aber nachträglich abgeglichen werden.
Wenn Ihre Zahlungsmeldungen von Stripe an der Signaturprüfung scheitern und Bestellungen hängen bleiben, gehen wir die Kette gern mit Ihnen durch: Kontakt.