Czym webhooki Stripe Connect różnią się od zwykłych webhooków Stripe?

Zdarzenia Connect pochodzą z połączonych kont i niosą nagłówek Stripe-Account identyfikujący, które konto wyzwoliło zdarzenie. Mechanizm podpisu jest taki sam jak w zwykłym Stripe, ale musisz włączyć Events on Connected accounts w panelu i routować po nagłówku w handlerze.

Do czego służy nagłówek Stripe-Account?

Identyfikuje połączone konto, które wyzwoliło zdarzenie. Handler powinien je odczytać przed przetwarzaniem, bo ten sam typ zdarzenia może wyzwolić się na twojej platformie lub na połączonym koncie, a logika biznesowa się różni.

Jak testować webhook deautoryzacji lokalnie?

Skonfiguruj endpoint Connect z tunelem, połącz testowe konto Express lub Custom, potem deautoryzuj je z interfejsu testowego Connect. Zdarzenie account.application.deauthorized dociera do twojego lokalnego handlera — powtarzaj je w razie potrzeby, dopracowując logikę czyszczenia.

Webhooki Stripe Connect: przewodnik po testach lokalnych

Stripe Connect to inny ekosystem webhooków niż zwykły Stripe. Matematyka podpisu jest ta sama. Wszystko inne jest inne. Jeśli szukałeś, dlaczego twój handler Connect po cichu ignoruje account.application.deauthorized, ten artykuł jest dla ciebie.

Connect zmienia, jakie zdarzenia otrzymujesz

Zwykłe webhooki Stripe pochodzą z twojego konta platformy: charges, customers, subscriptions. Webhooki Connect pochodzą z połączonych kont i ze specyficznych dla Connect zdarzeń cyklu życia na twojej platformie. Lista mocno się pokrywa, ale zawiera zdarzenia, które widzisz tylko z włączonym Connect:

account.updated — status weryfikacji, capabilities, wymagania
account.application.deauthorized — połączone konto cofnęło twój dostęp
capability.updated — stany aktywacji payouts/transfers
person.created, person.updated — dla kont Custom i Express
payout.failed, payout.paid — na połączonym koncie, nie twojej platformie

Większość zespołów odkrywa to po wdrożeniu. Testy lokalne wydobywają problem w minuty.

Nagłówek Stripe-Account zmienia wszystko

Gdy zdarzenie dzieje się na połączonym koncie, Stripe dołącza nagłówek Stripe-Account z ID połączonego konta (acct_xxx). Twój handler musi routować po tym nagłówku, nie po tym, co jest w payloadzie.

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);

Jeśli zapomnisz odczytać nagłówek, handler traktuje każde zdarzenie Connect, jakby zaszło na twojej platformie. Bugi z tego wzorca zwykle pojawiają się jako „payout pokazuje się dla złego sprzedawcy”.

Testowanie Connect lokalnie z PortPreview

Konfiguracja jest taka sama jak zwykłe lokalne testowanie Stripe, plus jeden dodatkowy krok:

Uruchom aplikację platformy lokalnie.
Uruchom tunel: npx portpreview 3000.
W panelu Stripe dodaj URL tunelu jako endpoint webhooka i zaznacz opcję Events on Connected accounts. To przełącznik, który zmienia cały strumień zdarzeń.
Użyj testowego połączonego konta Express lub Custom. Tryb testowy Stripe zawiera fałszywego twórcę konta „Jenny Rosen”, który wyzwala realistyczne zdarzenia.
Wyzwalaj zdarzenia z interfejsu testowego Connect: ukończ onboarding, zażądaj payout, deautoryzuj konto.

Przepływ deautoryzacji jest tym trudnym

Gdy połączone konto cofa dostęp twojej aplikacji, Stripe wyzwala account.application.deauthorized dokładnie raz. Jeśli twój handler się wywali, zwróci 5xx lub nie potwierdzi zdarzenia na czas, Stripe ponawia — ale połączone konto już zniknęło. Twoje kolejne wywołania API dla tego konta zwracają 401.

Testuj przepływ deauth ostrożnie. Użyj trybu testowego Connect, by deautoryzować testowe konto, przechwyć webhook i uruchom logikę czyszczenia na przechwyconym payloadzie. Powtarzaj, aż ścieżka będzie kuloodporna.

Express vs Standard vs Custom

Typ konta zmienia, jakie zdarzenia person/capability otrzymujesz. Konta Express i Custom emitują zdarzenia person.*, bo twoja platforma pomaga ukończyć onboarding. Konta Standard obsługują własny onboarding przez ekrany hostowane przez Stripe, więc widzisz mniej zdarzeń. Jeśli zmieniasz typ konta w trakcie projektu — a ludzie to robią — twój handler webhooków wymaga dostosowania.

Co faktycznie byśmy zrobili

Dla prawdziwego marketplace z analityką na poziomie platformy i raportowaniem per sprzedawca zbuduj dwie odrębne ścieżki handlera od pierwszego dnia: jedną dla zdarzeń platformy (bez nagłówka Stripe-Account), jedną dla zdarzeń połączonych kont. Routuj na górze funkcji. To unika 90% bugów „czy to dla nas, czy dla sprzedawcy” później.

Webhooki Connect dzielą schemat podpisu Stripe, więc mechanika weryfikacji jest identyczna jak zwykłe testowanie webhooków Stripe. Po tło matematyki podpisu u dostawców zobacz przewodnik weryfikacji podpisu. Dołącz do listy oczekujących PortPreview, by testować Connect z wbudowanym przechwytywaniem i powtórką.