Stripe-Webhook mit HTTP 500: Fehler systematisch beheben
1. Entscheiden, wo der Stripe-Webhook mit HTTP 500 scheitert
Wenn Stripe für einen Webhook 500 Internal Server Error meldet, steht zuerst eine konkrete Entscheidung an: Sollten Sie den Endpunkt sofort ändern oder fehlgeschlagene Ereignisse erneut zustellen? Ich würde zunächst beides zurückstellen und ermitteln, welcher Dienst die Antwort ausgelöst hat. Der Status kann von Ihrer Anwendung stammen, aber auch von einem Reverse-Proxy, einem Gateway oder einer Hosting-Schicht. Eine vorschnelle Wiederholung hilft nicht, wenn die Ursache weiter besteht, und kann riskant sein, falls die Anwendung das Ereignis vor dem Fehler bereits teilweise verarbeitet hat.
Öffnen Sie im Stripe-Dashboard den betroffenen Webhook-Endpunkt und sehen Sie sich die Details der einzelnen Zustellung an. Notieren Sie Ereignis-ID, Ereignistyp, Zeitpunkt, HTTP-Status, Antworttext und Anzahl der Versuche. Gleichen Sie diese Angaben mit den Anwendungs- und Serverlogs ab. Eine passende Ereignis-ID und ein ähnlicher Zeitstempel erleichtern die Zuordnung, besonders wenn mehrere Zustellungen gleichzeitig eintreffen. Der Status allein beweist weder, dass Stripe fehlerhaft arbeitet, noch dass Ihre Anwendung keinerlei Änderungen vorgenommen hat.
2. Ursachen in Handler, Signaturprüfung und Infrastruktur eingrenzen
Ein häufiger Auslöser ist eine nicht abgefangene Ausnahme im Endpunktcode. Das kann ein Datenbankfehler, ein Timeout bei einem nachgelagerten Dienst, ein unerwarteter leerer Wert oder ein Fehler beim Zugriff auf ein Pflichtfeld sein. Auch Unterschiede zwischen Ereignistypen sind relevant: Ein Handler, der für ein Ereignis ein bestimmtes Feld voraussetzt, kann bei einem anderen Typ scheitern. Zudem sollten Sie berücksichtigen, dass Ereignisobjekte je nach Inhalt und API-Version unterschiedliche Felder enthalten können. Prüfen Sie deshalb, ob der Code Werte kontrolliert, bevor er sie verwendet, und ob unbekannte Ereignistypen eine definierte Behandlung haben.
Auch Signaturprüfung und Infrastruktur können den Fehler verursachen oder verschleiern. Stripe signiert Webhook-Anfragen; zur Prüfung braucht Ihre Anwendung den unveränderten Request-Body und das richtige Geheimnis für genau den konfigurierten Endpunkt und die jeweilige Umgebung. Wenn Middleware den Body vorher verändert, kann die Prüfung fehlschlagen. Eine solche Ablehnung führt nicht zwangsläufig zu HTTP 500, doch eine unpassende Fehlerbehandlung kann aus einem erwartbaren Validierungsfehler einen internen Serverfehler machen. Prüfen Sie außerdem TLS, Proxy-Weiterleitungen, Firewall-Regeln, Laufzeitlimits und Erreichbarkeit: Ein vorgeschalteter Dienst kann Anfragen ablehnen oder verändern, bevor Ihr Handler sie erhält.
3. Dashboard, Logs und Handler Schritt für Schritt prüfen
Zustellung im Stripe-Dashboard untersuchen: Öffnen Sie die fehlgeschlagene Zustellung und halten Sie Ereignis-ID, Ereignistyp, Endpunkt, Status und Antwortdetails fest. Prüfen Sie, ob alle Ereignistypen betroffen sind oder nur bestimmte. Vergleichen Sie den Zeitpunkt mit den Logs von Anwendung, Hosting und Proxy. Wenn die Antwort einen Fehlertext enthält, nutzen Sie ihn als Hinweis, nicht als vollständige Diagnose: Er kann gekürzt sein oder von einer vorgeschalteten Schicht stammen. Achten Sie auch darauf, ob ein anderer Endpunkt dasselbe Ereignis erfolgreich empfängt.
Signatur und Laufzeitkonfiguration kontrollieren: Vergleichen Sie das konfigurierte Webhook-Geheimnis mit dem Geheimnis des passenden Endpunkts und der richtigen Stripe-Umgebung. Test- und Live-Endpunkte können unterschiedliche Geheimnisse haben. Prüfen Sie, ob die Signatur vor dem Parsen oder Umschreiben des Bodys validiert wird und ob die Anwendung den unveränderten Inhalt erhält. Kontrollieren Sie relevante Einstellungen wie URL, TLS-Zertifikat, Proxy-Ziel und Zeitlimits. In Logs gehören Fehlerklasse, Stacktrace und Ereignis-ID, aber weder das Geheimnis noch vollständige Kartendaten oder andere unnötig sensible Informationen.
Handler robust und wiederholbar gestalten: Lassen Sie den Endpunkt die Anfrage zügig validieren und das Ereignis zuverlässig speichern. Längere Arbeit, etwa der Aufruf weiterer Dienste, kann anschließend über eine Warteschlange laufen. Sorgen Sie dafür, dass dieselbe Ereignis-ID nicht doppelte Änderungen auslöst, und behandeln Sie unbekannte Ereignistypen kontrolliert. Antworten Sie erfolgreich erst dann, wenn das Ereignis zuverlässig angenommen wurde; ein Erfolgscode darf keine Verarbeitung vortäuschen, die noch nicht gesichert ist. Testen Sie die Änderung zunächst mit passenden Testereignissen. Eine erneute Zustellung im Dashboard sollte erst folgen, wenn Code, Konfiguration und möglicher Zwischenstand geprüft sind.
4. Wiederholungen und doppelte Verarbeitung sicher vermeiden
Stripe kann Webhooks nach fehlgeschlagenen Zustellungen erneut senden. Daher sollte die Verarbeitung idempotent sein: Derselbe Zustellversuch darf nicht unbeabsichtigt eine zweite Bestellung, Gutschrift oder sonstige geschäftliche Änderung auslösen. Speichern Sie die Ereignis-ID dauerhaft und prüfen Sie vor einer erneuten Verarbeitung, ob das Ereignis bereits angenommen wurde. Ergänzend sollte die Anwendung den Zustand des betroffenen Vorgangs kontrollieren, denn ein Fehler kann nach einer erfolgreichen Teilaktion auftreten. Eine Ereignis-ID allein ersetzt nicht die Prüfung der tatsächlichen Datenbankänderung.
Ich würde außerdem Überwachung für Fehlerrate, Antwortzeiten und offene Aufgaben einrichten. Ein Alarm ist hilfreicher, wenn er den betroffenen Endpunkt und eine Ereignis-ID enthält, ohne vertrauliche Nutzdaten offenzulegen. Nach einer Code- oder Konfigurationsänderung sollten Sie die folgenden Zustellungen beobachten und zunächst gezielt einzelne Ereignisse erneut anstoßen. Viele gleichzeitige Wiederholungen können die Anwendung zusätzlich belasten und verschleiern, ob die Korrektur greift. Halten Sie Test- und Live-Konfiguration getrennt, speichern Sie Geheimnisse nicht im Quellcode und verwenden Sie für einen Austausch einen geregelten, sicheren Prozess. So lassen sich Ursachen besser eingrenzen, ohne unnötige Nebenwirkungen zu erzeugen.
5. Häufige Fragen zu Stripe-Webhooks mit HTTP 500
Q1. Bedeutet HTTP 500, dass Stripe das Ereignis nicht verarbeitet hat?
A1. Nein, der Status sagt nicht sicher aus, wie weit Ihre Anwendung bei der Verarbeitung gekommen ist. Sie kann bereits Daten gespeichert oder eine Nebenwirkung ausgelöst haben, bevor der Fehler auftrat. Prüfen Sie Logs und Anwendungszustand anhand der Ereignis-ID, bevor Sie eine erneute Zustellung auslösen. Eine Erkennung doppelter Ereignisse schützt zusätzlich vor wiederholten Änderungen.
Q2. Soll ich ein fehlgeschlagenes Ereignis sofort erneut zustellen?
A2. Warten Sie, bis die Ursache behoben und eine mögliche Teilverarbeitung geprüft ist. Sonst kann die erneute Zustellung denselben Fehler wiederholen oder eine doppelte Aktion verursachen. Nutzen Sie die Zustellfunktion im Dashboard gezielt und kontrollieren Sie anschließend den neuen Status sowie die Anwendungslogs. Bei vielen Fehlern sollte zuerst der Endpunkt stabilisiert werden, bevor mehrere Ereignisse erneut angestoßen werden.
Q3. Warum scheitern nur bestimmte Ereignistypen mit HTTP 500?
A3. Verschiedene Ereignistypen enthalten unterschiedliche Daten und lösen oft unterschiedliche Codepfade aus. Ein Handler kann etwa ein optionales Feld voraussetzen oder einen unbekannten Typ nicht abfangen. Vergleichen Sie Ereignistyp, vorhandene Felder und Stacktrace, und prüfen Sie, ob der Code fehlende Werte sicher behandelt. Testen Sie betroffene Typen vor der produktiven Bereitstellung der Änderung.