Stripe Connect webhook: คู่มือทดสอบในเครื่อง

Stripe Connect เป็นระบบนิเวศ webhook ที่ต่างจาก Stripe ทั่วไป คณิตศาสตร์ลายเซ็นเหมือนกัน ที่เหลือทั้งหมดต่างกัน ถ้าคุณตามหาว่าทำไม handler Connect ของคุณเพิกเฉยต่อ account.application.deauthorized เงียบ ๆ บทความนี้เพื่อคุณ

Connect เปลี่ยนว่าคุณได้รับอีเวนต์ใด

webhook Stripe ทั่วไปมาจากบัญชีแพลตฟอร์มของคุณ: charges, customers, subscriptions webhook Connect มาจากบัญชีที่เชื่อมต่อและจากอีเวนต์วงจรชีวิตเฉพาะ Connect บนแพลตฟอร์มของคุณ รายการทับซ้อนกันมากแต่รวมอีเวนต์ที่คุณเห็นเฉพาะเมื่อเปิด Connect:

• account.updated — สถานะการยืนยัน capability ข้อกำหนด
• account.application.deauthorized — บัญชีที่เชื่อมต่อเพิกถอนการเข้าถึงของคุณ
• capability.updated — สถานะการเปิดใช้ payouts/transfers
• person.created, person.updated — สำหรับบัญชี Custom และ Express
• payout.failed, payout.paid — บนบัญชีที่เชื่อมต่อ ไม่ใช่แพลตฟอร์มของคุณ

ทีมส่วนใหญ่ค้นพบสิ่งนี้หลัง deploy การทดสอบในเครื่องเผยปัญหาในไม่กี่นาทีแทน

header Stripe-Account เปลี่ยนทุกอย่าง

เมื่ออีเวนต์เกิดบนบัญชีที่เชื่อมต่อ Stripe แนบ header Stripe-Account พร้อม ID ของบัญชีที่เชื่อมต่อ (acct_xxx) handler ของคุณต้อง route ตาม header นั้น ไม่ใช่ตามสิ่งที่อยู่ใน 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);

ถ้าลืมอ่าน header, handler จะถือว่าทุกอีเวนต์ Connect เกิดบนแพลตฟอร์มของคุณ บั๊กจากแพทเทิร์นนี้มักปรากฏเป็น "payout แสดงให้ร้านค้าผิดคน"

ทดสอบ Connect ในเครื่องด้วย PortPreview

การตั้งค่าเหมือนการทดสอบ Stripe ทั่วไปในเครื่อง บวกหนึ่งขั้นเพิ่ม:

1. รันแอปแพลตฟอร์มในเครื่อง
2. เริ่ม tunnel: npx portpreview 3000
3. ในแดชบอร์ด Stripe เพิ่ม URL tunnel เป็น endpoint webhook และ ติ๊กตัวเลือก Events on Connected accounts นี่คือสวิตช์ที่เปลี่ยนสตรีมอีเวนต์ทั้งหมด
4. ใช้บัญชีเชื่อมต่อทดสอบ Express หรือ Custom โหมดทดสอบของ Stripe มีตัวสร้างบัญชีปลอม "Jenny Rosen" ที่ยิงอีเวนต์สมจริง
5. ทริกเกอร์อีเวนต์จากอินเทอร์เฟซทดสอบ Connect: ทำ onboarding ให้เสร็จ ขอ payout เพิกถอนบัญชี

flow การเพิกถอนเป็นตัวยาก

เมื่อบัญชีที่เชื่อมต่อเพิกถอนการเข้าถึงแอปของคุณ Stripe ยิง account.application.deauthorized เพียงครั้งเดียวพอดี ถ้า handler ของคุณ crash คืน 5xx หรือไม่ยืนยันอีเวนต์ทันเวลา Stripe ลองใหม่ — แต่บัญชีที่เชื่อมต่อหายไปแล้ว การเรียก API ต่อ ๆ มาสำหรับบัญชีนั้นคืน 401

ทดสอบ flow deauth อย่างระมัดระวัง ใช้โหมดทดสอบ Connect เพิกถอนบัญชีทดสอบ จับ webhook และรันตรรกะ cleanup กับ payload ที่จับไว้ replay จนเส้นทางกันกระสุน

Express vs Standard vs Custom

ประเภทบัญชีเปลี่ยนว่าคุณได้รับอีเวนต์ person/capability ใด บัญชี Express และ Custom ปล่อยอีเวนต์ person.* เพราะแพลตฟอร์มของคุณช่วยทำ onboarding ให้เสร็จ บัญชี Standard จัดการ onboarding ของตัวเองผ่านหน้าจอที่ Stripe โฮสต์ คุณจึงเห็นอีเวนต์น้อยกว่า ถ้าคุณเปลี่ยนประเภทบัญชีกลางโปรเจกต์ — และคนทำกัน — handler webhook ของคุณต้องปรับ

สิ่งที่เราจะทำจริง

สำหรับมาร์เก็ตเพลสจริงที่มี analytics ระดับแพลตฟอร์มและรายงานต่อร้านค้า สร้างเส้นทาง handler แยกสองทางตั้งแต่วันแรก: ทางหนึ่งสำหรับอีเวนต์แพลตฟอร์ม (ไม่มี header Stripe-Account) อีกทางสำหรับอีเวนต์บัญชีที่เชื่อมต่อ route ที่ต้นฟังก์ชัน นี่เลี่ยงบั๊ก "นี่สำหรับเราหรือร้านค้า" 90% ในภายหลัง

webhook Connect ใช้ scheme ลายเซ็นของ Stripe ร่วมกัน กลไกการตรวจจึงเหมือนการทดสอบ webhook Stripe ทั่วไป ทุกประการ สำหรับพื้นหลังคณิตศาสตร์ลายเซ็นข้ามผู้ให้บริการ ดูคู่มือการตรวจลายเซ็น เข้าร่วมรายชื่อรอ PortPreview เพื่อทดสอบ Connect พร้อมจับและ replay ในตัว