वेटलिस्ट में शामिल हों
सभी लेख
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 — जुड़े खाते पर, आपके प्लेटफ़ॉर्म पर नहीं

अधिकांश टीमें इसे deploy के बाद खोजती हैं। लोकल टेस्टिंग बजाय कुछ मिनटों में समस्या उजागर कर देती है।

Stripe-Account हेडर सब कुछ बदल देता है

जब कोई इवेंट जुड़े खाते पर होता है, Stripe जुड़े खाते की ID (acct_xxx) के साथ एक Stripe-Account हेडर जोड़ता है। आपके हैंडलर को उस हेडर पर route करना चाहिए, 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 गलत व्यापारी के लिए दिखता है" के रूप में प्रकट होते हैं।

PortPreview के साथ Connect को लोकल टेस्ट करना

सेटअप सामान्य Stripe लोकल टेस्टिंग जैसा ही है, साथ में एक अतिरिक्त चरण:

  1. अपना प्लेटफ़ॉर्म ऐप लोकल चलाएँ।
  2. एक टनल शुरू करें: npx portpreview 3000।
  3. Stripe डैशबोर्ड में टनल URL को वेबहुक endpoint के रूप में जोड़ें और Events on Connected accounts विकल्प को चेक करें। यही वह टॉगल है जो पूरी इवेंट स्ट्रीम बदल देता है।
  4. एक टेस्ट Express या Custom जुड़ा खाता उपयोग करें। Stripe टेस्ट मोड में एक नकली "Jenny Rosen" खाता निर्माता शामिल है जो यथार्थवादी इवेंट फ़ायर करता है।
  5. Connect टेस्ट इंटरफ़ेस से इवेंट ट्रिगर करें: onboarding पूरा करें, payout माँगें, एक खाता deauthorize करें।

deauthorization flow कठिन वाला है

जब एक जुड़ा खाता आपके एप्लिकेशन की पहुँच रद्द करता है, Stripe account.application.deauthorized को ठीक एक बार फ़ायर करता है। यदि आपका हैंडलर crash होता है, 5xx लौटाता है, या समय पर इवेंट स्वीकार नहीं करता, Stripe पुनः प्रयास करता है — पर जुड़ा खाता पहले ही चला गया है। उस खाते के लिए आपके बाद के API कॉल 401 लौटाते हैं।

deauth flow को सावधानी से टेस्ट करें। टेस्ट खाते को deauthorize करने के लिए Connect टेस्ट मोड उपयोग करें, वेबहुक कैप्चर करें, और कैप्चर किए payload के विरुद्ध अपनी cleanup लॉजिक चलाएँ। पथ अभेद्य होने तक replay करें।

Express बनाम Standard बनाम Custom

खाता प्रकार बदलता है कि आप कौन-से person/capability इवेंट प्राप्त करते हैं। Express और Custom खाते person.* इवेंट उत्सर्जित करते हैं क्योंकि आपका प्लेटफ़ॉर्म onboarding पूरा करने में मदद करता है। Standard खाते Stripe-होस्टेड स्क्रीन से अपना onboarding संभालते हैं, इसलिए आप कम इवेंट देखते हैं। यदि आप प्रोजेक्ट के बीच में खाता प्रकार बदलते हैं — और लोग बदलते हैं — आपके वेबहुक हैंडलर को समायोजन चाहिए।

हम वास्तव में क्या करेंगे

प्लेटफ़ॉर्म-स्तरीय analytics और प्रति-व्यापारी रिपोर्टिंग वाले असली मार्केटप्लेस के लिए, पहले दिन से दो अलग हैंडलर पथ बनाएँ: एक प्लेटफ़ॉर्म इवेंट के लिए (Stripe-Account हेडर के बिना), एक जुड़े-खाता इवेंट के लिए। फ़ंक्शन के शीर्ष पर route करें। यह बाद में 90% "यह हमारे लिए है या व्यापारी के लिए" बग से बचाता है।

Connect वेबहुक Stripe की हस्ताक्षर स्कीम साझा करते हैं, इसलिए सत्यापन यांत्रिकी सामान्य Stripe वेबहुक टेस्टिंग के समान है। प्रदाताओं में हस्ताक्षर गणित की पृष्ठभूमि के लिए, हस्ताक्षर सत्यापन गाइड देखें। अंतर्निर्मित कैप्चर और replay के साथ Connect टेस्ट करने के लिए PortPreview वेटलिस्ट में शामिल हों।

अक्सर पूछे जाने वाले प्रश्न

Stripe Connect वेबहुक सामान्य Stripe वेबहुक से कैसे अलग हैं?
Connect इवेंट जुड़े खातों से आते हैं और एक Stripe-Account हेडर ले जाते हैं जो पहचानता है कि किस खाते ने इवेंट फ़ायर किया। हस्ताक्षर तंत्र सामान्य Stripe जैसा ही है, पर आपको डैशबोर्ड में Events on Connected accounts सक्षम करना होगा और हैंडलर में हेडर द्वारा route करना होगा।
Stripe-Account हेडर किसलिए उपयोग होता है?
यह उस जुड़े खाते की पहचान करता है जिसने इवेंट ट्रिगर किया। हैंडलर को प्रोसेस करने से पहले इसे पढ़ना चाहिए क्योंकि वही इवेंट प्रकार आपके प्लेटफ़ॉर्म पर या जुड़े खाते पर फ़ायर हो सकता है, और बिज़नेस लॉजिक भिन्न होती है।
मैं deauthorization वेबहुक को लोकल कैसे टेस्ट करूँ?
टनल के साथ एक Connect endpoint सेट करें, एक टेस्ट Express या Custom खाता जोड़ें, फिर Connect टेस्ट इंटरफ़ेस से उसे deauthorize करें। account.application.deauthorized इवेंट आपके लोकल हैंडलर पर आता है — cleanup लॉजिक ट्यून करते समय आवश्यकतानुसार उसे replay करें।