Shopify वेबहुक को लोकल बिना किसी आश्चर्य के टेस्ट करें

लोकल डेवलपमेंट में अधिकांश Shopify वेबहुक बग एक लाइन पर सिमट आते हैं: HMAC base64-एन्कोडेड है, hex नहीं। यदि आप .digest('hex') कॉल करते हैं और X-Shopify-Hmac-Sha256 से तुलना करते हैं, जाँच कभी पास नहीं होगी — सही shared secret के साथ भी। हमने सीनियर इंजीनियरों को इस एक अक्षर पर एक दोपहर गँवाते देखा है।

base64 का जाल

Stripe hex उपयोग करता है। GitHub hex उपयोग करता है (sha256= प्रीफ़िक्स के साथ)। Shopify base64 उपयोग करता है। तीन प्रदाता, तीन एन्कोडिंग। आपके वेरिफ़ायर का पहला संस्करण लगभग निश्चित रूप से किसी अन्य प्रोजेक्ट से snippet कॉपी करेगा और चुपचाप विफल होगा।

वेरिफ़िकेशन ऐसा दिखना चाहिए:

const hmac = crypto
  .createHmac('sha256', SHOPIFY_API_SECRET)
  .update(rawBody)         // raw body, not JSON-parsed
  .digest('base64');       // base64, not hex

const valid = crypto.timingSafeEqual(
  Buffer.from(hmac),
  Buffer.from(req.headers['x-shopify-hmac-sha256']),
);

एन्कोडिंग के अलावा दो चीज़ें मायने रखती हैं। body को raw, बिना पार्स किए बाइट होना चाहिए। और तुलना timing-safe होनी चाहिए — string समानता एक-एक बाइट जानकारी लीक करती है।

क्यों एक टनल इसे आसान बनाता है

आप Shopify की shopify app dev कमांड भी उपयोग कर सकते हैं, जो एक आंतरिक टनल खड़ा करती है। काम करती है। पर यह आपके dev सर्वर को अपनी प्रक्रिया में लपेटती है, log को एक खास तरीके से निगलती है, और कोई replay बटन नहीं देती। "hello world" से आगे की ऐप डेवलपमेंट के लिए, एक स्थिर सार्वजनिक URL और अनुरोध कैप्चर वाला localhost टनल CLI के शुरुआती सेटअप में बचाए समय से अधिक समय बचाता है।

npx portpreview 3000

आप HTTPS URL को Partners डैशबोर्ड में अपने ऐप की वेबहुक कॉन्फ़िगरेशन में पेस्ट करते हैं, एक टेस्ट स्टोर से इवेंट ट्रिगर करते हैं, और अनुरोध सभी हेडर के साथ आपके लोकल हैंडलर में आ गिरता है।

टेस्ट स्टोर: वह हिस्सा जिसे Shopify दस्तावेज़ सरसरी छू लेता है

कुछ भी जोड़ने से पहले जानने योग्य दो बातें:

• डेवलपमेंट स्टोर सभी वेबहुक इवेंट फ़ायर करते हैं। ऑर्डर निर्माण, fulfillment, इन्वेंटरी — सब। आपको कुछ नकली बनाने की ज़रूरत नहीं; बस अपना ऐप dev स्टोर पर इंस्टॉल करें और क्लिक करें।
• वेबहुक secret प्रति ऐप और प्रति डिलीवरी चैनल भिन्न होता है। यदि आप EventBridge या Pub/Sub भी सब्सक्राइब करते हैं, HMAC व्यवहार अलग है। यहाँ हम सादे HTTPS वेबहुक डिलीवरी की बात कर रहे हैं।

चरण-दर-चरण सेटअप

1. जिस पोर्ट का उपयोग करते हैं (3000 आम है) उस पर अपना ऐप लोकल शुरू करें।
2. npx portpreview 3000 चलाएँ और छपा HTTPS URL कॉपी करें।
3. Shopify Partners डैशबोर्ड में अपना ऐप खोलें और Configuration → Webhooks पर जाएँ।
4. वेबहुक endpoint को https://your-tunnel.portpreview.dev/api/webhooks/shopify (या आपके ऐप द्वारा उपयोग किया path) सेट करें।
5. ऐप को dev स्टोर पर इंस्टॉल करें, फिर एक इवेंट ट्रिगर करें — एक ड्राफ्ट ऑर्डर बनाएँ, एक आइटम fulfill करें, इन्वेंटरी बदलें।
6. अनुरोध को आते देखें। हेडर और body निरीक्षण करें। हर हैंडलर फ़िक्स के बाद कैप्चर किया अनुरोध replay करें।

वे गलतियाँ जो हम लगातार देखते हैं

वेरिफ़िकेशन से पहले body पार्स

यदि आप app.use(express.json()) को अपने वेबहुक रूट से पहले रखते हैं, जब आप वेरिफ़ाई करने की कोशिश करते हैं तब तक raw बाइट चले जाते हैं। raw-body पार्सर केवल वेबहुक path पर माउंट करें, या किसी भी JSON पार्सिंग से पहले अनुरोध stream से body मैन्युअल खींचें।

उलझे हुए secret

Partners ऐप secret, Storefront API टोकन जैसा नहीं है। वेबहुक HMAC ऐप secret उपयोग करता है। यदि आप अपनी env फ़ाइल में shp_xxx को घूर रहे हैं, आपने गलत वाला पकड़ा।

समान दिखने वाले टेस्ट इवेंट

Shopify का "Send test notification" बटन एक placeholder body वाला सिंथेटिक इवेंट डिलीवर करता है। उस टेस्ट इवेंट पर हस्ताक्षर असली है, पर payload स्थिर है। यथार्थवादी payload-आकार टेस्टिंग के लिए, dev स्टोर से ही इवेंट ट्रिगर करें।

ऐप dev के लिए replay पर समझौता नहीं

Shopify विफल वेबहुक को घातांकी backoff के साथ 48 घंटे तक पुनः प्रयास करता है। उदार है, पर इटरेट करते समय आप अगले retry का इंतज़ार नहीं करना चाहते। पहली डिलीवरी को अपने टनल के अनुरोध इतिहास में कैप्चर करें और अपने लोकल हैंडलर के विरुद्ध माँग पर replay करें।

जब लोकल पर्याप्त नहीं रहता

शॉप पंजीकरण flow, GDPR वेबहुक और सब्सक्रिप्शन बिलिंग बदलाव deploy किए वातावरण के विरुद्ध सत्यापित करना आसान है क्योंकि वे Shopify की अपनी खाता स्थिति से इंटरैक्ट करते हैं। बाकी सब के लिए — payload पार्सिंग, हस्ताक्षर सत्यापन, बिज़नेस लॉजिक — लोकल तेज़ है।

सभी प्रदाताओं में अंतर्निहित हस्ताक्षर गणित के लिए, हमारी वेबहुक हस्ताक्षर सत्यापन गाइड पढ़ें। यदि आप अंतर्निर्मित replay वाला टनल चाहते हैं तो PortPreview वेटलिस्ट में शामिल हों।