Wie unterscheiden sich Stripe-Connect-Webhooks von regulären Stripe-Webhooks?

Connect-Events kommen von verbundenen Konten und tragen einen Stripe-Account-Header, der angibt, welches Konto das Event gefeuert hat. Der Signatur-Mechanismus ist derselbe wie bei regulärem Stripe, aber du musst Events on Connected accounts im Dashboard aktivieren und in deinem Handler nach dem Header routen.

Wofür wird der Stripe-Account-Header verwendet?

Er identifiziert das verbundene Konto, das das Event ausgelöst hat. Dein Handler sollte ihn vor der Verarbeitung lesen, weil derselbe Event-Typ auf deiner Plattform oder auf einem verbundenen Konto feuern kann und die Business-Logik sich unterscheidet.

Wie teste ich den Deauthorization-Webhook lokal?

Richte einen Connect-Endpoint mit einem Tunnel ein, verbinde ein Test-Express- oder -Custom-Konto, dann deautorisiere es über das Connect-Test-Interface. Das account.application.deauthorized-Event landet auf deinem lokalen Handler — replaye es nach Bedarf, während du die Cleanup-Logik feinjustierst.

Stripe-Connect-Webhooks: der Leitfaden zum lokalen Testen

Stripe Connect ist ein anderes Webhook-Ökosystem als reguläres Stripe. Die Signatur-Mathematik ist gleich. Alles andere ist anders. Wenn du gejagt hast, warum dein Connect-Handler account.application.deauthorized stillschweigend ignoriert, ist dieser Artikel für dich.

Connect ändert, welche Events du empfängst

Reguläre Stripe-Webhooks kommen von deinem Plattform-Account: Charges, Customers, Subscriptions. Connect-Webhooks kommen von verbundenen Konten und von Connect-spezifischen Lifecycle-Events auf deiner Plattform. Die Liste überschneidet sich stark, enthält aber Events, die du nur mit aktiviertem Connect siehst:

account.updated — Verifizierungsstatus, Capabilities, Requirements
account.application.deauthorized — verbundenes Konto hat deinen Zugang widerrufen
capability.updated — Aktivierungsstatus für Payouts/Transfers
person.created, person.updated — für Custom- und Express-Konten
payout.failed, payout.paid — auf dem verbundenen Konto, nicht deiner Plattform

Die meisten Teams entdecken das nach dem Deploy. Lokales Testen bringt das Problem stattdessen in Minuten ans Licht.

Der Stripe-Account-Header ändert alles

Wenn ein Event auf einem verbundenen Konto passiert, hängt Stripe einen Stripe-Account-Header mit der ID des verbundenen Kontos an (acct_xxx). Dein Handler muss auf diesem Header routen, nicht auf dem, was im Payload steckt.

const connectedAccountId = req.headers['stripe-account'];
const event = stripe.webhooks.constructEvent(
  rawBody,
  req.headers['stripe-signature'],
  endpointSecret,
);

// Now process the event in the context of connectedAccountId
await handleConnectEvent(event, connectedAccountId);

Wenn du vergisst, den Header zu lesen, behandelt dein Handler jedes Connect-Event so, als wäre es auf deiner Plattform passiert. Bugs aus diesem Muster zeigen sich meist als „das Payout erscheint beim falschen Händler“.

Connect lokal mit PortPreview testen

Das Setup ist dasselbe wie beim regulären lokalen Stripe-Testen, plus ein zusätzlicher Schritt:

Lass deine Plattform-App lokal laufen.
Starte einen Tunnel: npx portpreview 3000.
Füge im Stripe-Dashboard die Tunnel-URL als Webhook-Endpoint hinzu und aktiviere die Option Events on Connected accounts. Das ist der Toggle, der den gesamten Event-Stream ändert.
Nutze ein Test-Express- oder -Custom-verbundenes-Konto. Der Stripe-Testmodus enthält einen Fake-„Jenny Rosen“-Account-Creator, der realistische Events feuert.
Triggere Events aus dem Connect-Test-Interface: Onboarding abschließen, ein Payout anfordern, ein Konto deautorisieren.

Der Deauthorization-Flow ist der schwierige

Wenn ein verbundenes Konto den Zugang deiner Anwendung widerruft, feuert Stripe account.application.deauthorized genau einmal. Wenn dein Handler crasht, ein 5xx zurückgibt oder das Event nicht rechtzeitig bestätigt, wiederholt Stripe — aber das verbundene Konto ist schon weg. Deine nachfolgenden API-Calls für dieses Konto geben 401 zurück.

Teste den Deauth-Flow sorgfältig. Nutze den Connect-Testmodus, um das Testkonto zu deautorisieren, den Webhook zu erfassen und deine Cleanup-Logik gegen das erfasste Payload laufen zu lassen. Replaye, bis der Pfad kugelsicher ist.

Express vs. Standard vs. Custom

Der Kontotyp ändert, welche Person-/Capability-Events du empfängst. Express- und Custom-Konten emittieren person.*-Events, weil deine Plattform beim Abschluss des Onboardings hilft. Standard-Konten erledigen ihr eigenes Onboarding über Stripe-gehostete Screens, also siehst du weniger Events. Wenn du Kontotypen mitten im Projekt wechselst — und Leute tun das — braucht dein Webhook-Handler eine Anpassung.

Was wir tatsächlich tun würden

Für einen echten Marketplace mit Plattform-Level-Analytics und Reporting pro Händler baue von Tag eins an zwei eigenständige Handler-Pfade: einen für Plattform-Events (kein Stripe-Account-Header), einen für Events verbundener Konten. Route am Anfang der Funktion. Das vermeidet 90 % der „ist das für uns oder für den Händler“-Bugs später.

Connect-Webhooks teilen Stripes Signatur-Schema, also ist die Verifikations-Mechanik identisch zum regulären Stripe-Webhook-Testen. Für Hintergrund zur Signatur-Mathematik über Anbieter hinweg siehe den Signatur-Verifikations-Leitfaden. Tritt der PortPreview-Warteliste bei, um Connect mit eingebautem Capture und Replay zu testen.