Mit dem lokalen Testen von Stripe-Webhooks validierst du deine Zahlungs-Event-Handler direkt auf deinem Rechner, bevor du in Produktion gehst. Du startest deine App lokal, machst sie über eine öffentliche HTTPS-URL erreichbar und empfängst echte Stripe-Test-Events – mit vollständig intakter Signaturprüfung.
Warum Stripe-Webhooks eine öffentliche URL brauchen
Stripe stellt Webhook-Events über das öffentliche Internet an eine konfigurierte Endpunkt-URL zu. Adressen wie 127.0.0.1:3000 sind von Stripes Servern nicht erreichbar, daher braucht lokale Entwicklung eine Brücke. Ein Localhost-Tunnel bildet eine öffentliche HTTPS-URL auf deinen lokalen Prozess ab – ohne Router- oder Firewall-Änderungen.
Was du vor dem Testen brauchst
- Ein Stripe-Konto im Testmodus.
- Eine lokale App mit einer Webhook-Route (zum Beispiel
/api/webhooks/stripe). - Dein Stripe-Webhook-Signing-Secret als Umgebungsvariable hinterlegt.
- Ein Tunnel-Tool, das die Request-Header für die Signaturprüfung erhält.
Schritt für Schritt: Stripe-Webhooks lokal testen mit PortPreview
- Starte deine Anwendung lokal auf dem gewünschten Port.
- Führe
npx portpreview 3000aus, um eine öffentliche HTTPS-URL zu erzeugen. - Gehe im Stripe-Dashboard zu Entwickler → Webhooks und füge die Tunnel-URL plus deinen Webhook-Pfad hinzu.
- Wähle die Events aus, die du testen willst (zum Beispiel
checkout.session.completed,invoice.paid). - Löse Test-Events über das Stripe-Dashboard oder die CLI aus und inspiziere jede Zustellung.
- Prüfe, dass dein Handler eine 2xx-Antwort zurückgibt und die Signaturvalidierung besteht.
PortPreview erfasst Header, Body und Antwortstatus, sodass du fehlgeschlagene Zustellungen debuggen kannst, ohne allein aus Server-Logs raten zu müssen.
Stripe-Webhook-Signaturen lokal validieren
Deaktiviere die Signaturprüfung niemals während der Entwicklung. Stripe signiert jedes Payload mit deinem Webhook-Secret, und dein Handler sollte den Stripe-Signature-Header exakt so validieren wie in Produktion. Tunnel-Tools, die die Original-Header erhalten, lassen dich den echten Code-Pfad testen.
Häufige Signaturfehler beim lokalen Testen:
- Falsches Webhook-Secret (Dashboard-Secret vs. CLI-Secret).
- Ein bereits geparstes JSON-Body wird vor der Prüfung gelesen statt des rohen Request-Bodys.
- Zeitabweichung über Stripes Toleranzfenster hinaus.
Events, die sich lokal zu testen lohnen
Checkout und Abonnements
Teste checkout.session.completed, customer.subscription.created und invoice.payment_failed, um Provisionierung, Zugriffsfreigaben und Mahnlogik zu bestätigen.
Connect- und Marketplace-Flows
Wenn du Stripe Connect nutzt, validiere Account-Update-Events und Transfer-Benachrichtigungen mit verbundenen Test-Konten, bevor du live gehst.
Idempotenz und Retries
Stripe wiederholt fehlgeschlagene Zustellungen. Nutze Webhook-Replay, um zu bestätigen, dass dein Handler doppelte Events sicher verarbeitet.
Stripe CLI vs. Localhost-Tunnel
Die Stripe CLI kann Events mit stripe listen --forward-to weiterleiten, was sich gut für schnelle Checks eignet. Ein Localhost-Tunnel liefert dir eine stabile öffentliche URL, die du ins Dashboard einfügen, mit Teamkollegen teilen und providerübergreifend nutzen kannst – nicht nur für Stripe. Viele Teams nutzen beides: die CLI für schnelle Iteration, Tunnel für Integrationstests, die die Produktionskonfiguration abbilden.
Wann du von lokal zu Staging wechselst
Lokales Testen deckt Handler-Logik, Payload-Parsing und Signaturvalidierung ab. Wechsle zu Staging für umgebungsspezifische Checks wie verwaltete Secrets, Datenbankmigrationen und End-to-End-Release-Pipelines. Für die tägliche Arbeit an Zahlungsfeatures verkürzt lokales Stripe-Webhook-Testen die Iteration von Minuten auf Sekunden.
Lies unseren ausführlichen Leitfaden zum lokalen Debuggen von Webhooks oder tritt der PortPreview-Warteliste bei für Webhook-first-Tunnel-Workflows.