До списку очікування
Усі статті
StripeStripe Connectmarketplacewebhook debugging

Вебхуки Stripe Connect: посібник із локального тестування

Stripe Connect — це інша екосистема вебхуків, відмінна від звичайного Stripe. Математика підпису та сама. Усе інше інше. Якщо ви полювали за тим, чому ваш Connect-обробник мовчки ігнорує account.application.deauthorized, ця стаття для вас.

Connect змінює, які події ви отримуєте

Звичайні вебхуки Stripe приходять із вашого платформного акаунта: charges, customers, subscriptions. Вебхуки Connect приходять зі зв'язаних акаунтів і з Connect-специфічних подій життєвого циклу на вашій платформі. Список значною мірою перетинається, але включає події, які ви бачите лише з увімкненим Connect:

  • account.updated — статус верифікації, capabilities, вимоги
  • account.application.deauthorized — зв'язаний акаунт відкликав ваш доступ
  • capability.updated — стани активації payouts/transfers
  • person.created, person.updated — для Custom- та Express-акаунтів
  • payout.failed, payout.paid — на зв'язаному акаунті, не на вашій платформі

Більшість команд виявляють це після деплою. Локальне тестування натомість виявляє проблему за хвилини.

Заголовок Stripe-Account змінює все

Коли подія стається на зв'язаному акаунті, Stripe додає заголовок Stripe-Account з ID зв'язаного акаунта (acct_xxx). Ваш обробник має маршрутизувати за цим заголовком, а не за тим, що всередині payload.

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

Якщо забути прочитати заголовок, ваш обробник трактує кожну подію Connect так, ніби вона сталася на вашій платформі. Баги від цього патерну зазвичай проявляються як «payout показується не тому продавцю».

Тестування Connect локально з PortPreview

Налаштування таке саме, як при звичайному локальному тестуванні Stripe, плюс один додатковий крок:

  1. Запустіть ваш платформний застосунок локально.
  2. Запустіть тунель: npx portpreview 3000.
  3. У дашборді Stripe додайте URL тунелю як endpoint вебхука і позначте опцію Events on Connected accounts. Це перемикач, що змінює весь потік подій.
  4. Використайте тестовий Express- або Custom-зв'язаний акаунт. Тестовий режим Stripe включає фейкового творця акаунта «Jenny Rosen», що генерує реалістичні події.
  5. Тригерте події з тестового інтерфейсу Connect: завершіть онбординг, запросіть payout, деавторизуйте акаунт.

Потік деавторизації — найскладніший

Коли зв'язаний акаунт відкликає доступ вашого застосунку, Stripe генерує account.application.deauthorized рівно один раз. Якщо ваш обробник падає, повертає 5xx або не підтверджує подію вчасно, Stripe повторює — але зв'язаний акаунт уже зник. Ваші наступні API-виклики для цього акаунта повертають 401.

Ретельно тестуйте потік деавторизації. Використайте тестовий режим Connect, щоб деавторизувати тестовий акаунт, захопити вебхук і прогнати логіку очищення проти захопленого payload. Повторюйте, поки шлях не стане куленепробивним.

Express проти Standard проти Custom

Тип акаунта змінює, які події person/capability ви отримуєте. Express- та Custom-акаунти емітять події person.*, бо ваша платформа допомагає завершити онбординг. Standard-акаунти обробляють власний онбординг через розміщені Stripe екрани, тож ви бачите менше подій. Якщо ви змінюєте тип акаунта посеред проєкту — а люди це роблять — ваш обробник вебхуків потребує коригування.

Що б ми реально зробили

Для реального маркетплейсу з аналітикою на рівні платформи та звітністю за продавцями будуйте два окремі шляхи обробника з першого дня: один для подій платформи (без заголовка Stripe-Account), один для подій зв'язаних акаунтів. Маршрутизуйте на початку функції. Це уникає 90% багів «це для нас чи для продавця» згодом.

Вебхуки Connect використовують схему підпису Stripe, тож механіка верифікації ідентична звичайному тестуванню вебхуків Stripe. Щодо фону про математику підпису у провайдерів див. посібник із верифікації підпису. Приєднайтеся до списку очікування PortPreview, щоб тестувати Connect із вбудованим захопленням і повтором.

Поширені запитання

Чим вебхуки Stripe Connect відрізняються від звичайних вебхуків Stripe?
Події Connect приходять зі зв'язаних акаунтів і несуть заголовок Stripe-Account, що ідентифікує, який акаунт згенерував подію. Механізм підпису той самий, що в звичайного Stripe, але треба ввімкнути Events on Connected accounts у дашборді й маршрутизувати за заголовком в обробнику.
Для чого використовується заголовок Stripe-Account?
Він ідентифікує зв'язаний акаунт, що викликав подію. Обробник має прочитати його до обробки, бо той самий тип події може спрацювати на вашій платформі або на зв'язаному акаунті, і бізнес-логіка різниться.
Як тестувати вебхук деавторизації локально?
Налаштуйте endpoint Connect з тунелем, під'єднайте тестовий Express- або Custom-акаунт, потім деавторизуйте його з тестового інтерфейсу Connect. Подія account.application.deauthorized приходить на ваш локальний обробник — повторюйте її за потреби, поки налаштовуєте логіку очищення.