क्रिप्टो पेमेंट वेबहुक: इवेंट, सुरक्षा और भरोसेमंद ऑर्डर फ़ुलफ़िलमेंट

क्रिप्टो पेमेंट वेबहुक वे HTTP अनुरोध हैं जो पेमेंट गेटवे हर बार इनवॉइस का स्टेटस बदलने पर आपके सर्वर को भेजता है: ट्रांसफ़र मिला, चेन पर कन्फ़र्म हुआ, कम भुगतान, ज़्यादा भुगतान या एक्सपायर। आपका हैंडलर सिग्नेचर जाँचता है, ऑर्डर अपडेट करता है और डिलीवरी शुरू करता है। क्योंकि क्रिप्टो पेमेंट असिंक्रोनस आते हैं — ग्राहक के पेज छोड़ने के मिनटों बाद — सच का स्रोत वेबहुक है, ब्राउज़र नहीं।

यह गाइड इंटीग्रेशन के वेबहुक वाले हिस्से पर केंद्रित है: कौन-से इवेंट आते हैं, उन्हें कैसे वेरिफ़ाई करें, एक ही इवेंट दो बार आने पर प्रोसेसिंग सुरक्षित कैसे रखें, और टेस्टिंग व मॉनिटरिंग कैसे करें। इनवॉइस बनाने के लिए हमारी क्रिप्टो पेमेंट API इंटीग्रेशन गाइड देखें।

पोलिंग या रीडायरेक्ट के बजाय वेबहुक क्यों?

• रीडायरेक्ट सबूत नहीं — ग्राहक का "थैंक यू" पेज पर लौटना यह नहीं बताता कि पैसा आया या नहीं।
• पोलिंग बेकार है — हर खुले इनवॉइस के लिए हर कुछ सेकंड API से पूछना स्केल नहीं होता और फिर भी देर होती है।
• वेबहुक पुश है — कुछ भी बदलते ही गेटवे वेरिफ़ाई होने वाले सिग्नेचर के साथ आपको बताता है।

आपको मिलने वाले इवेंट

ये mistKET के इवेंट नाम हैं। दूसरे गेटवे मिलते-जुलते स्टेटस अलग नामों से इस्तेमाल करते हैं, इसलिए इन्हें एक ही जगह अपने ऑर्डर स्टेटस से मैप करें।

सिग्नेचर वेरिफ़ाई करना

कोई भी पब्लिक URL पर POST भेज सकता है, इसलिए हर वेबहुक का ऑथेंटिकेशन ज़रूरी है। mistKET हर डिलीवरी को HMAC-SHA256 से साइन करता है और ये हेडर भेजता है:

• X-Mistket-Event — इवेंट का नाम।
• X-Mistket-Timestamp — सिग्नेचर में शामिल Unix समय।
• X-Mistket-Signature — sha256= के बाद आपके वेबहुक सीक्रेट से {timestamp}.{raw body} का HMAC।
• X-Mistket-Delivery — लॉगिंग के लिए डिलीवरी ID।

1. रॉ बॉडी पढ़ें — JSON पार्स करने से पहले, क्योंकि दोबारा एन्कोड करने से बाइट बदल जाते हैं।
2. HMAC दोबारा निकालें — टाइमस्टैम्प, एक डॉट और रॉ बॉडी पर, अपने वेबहुक सीक्रेट से।
3. कॉन्स्टेंट टाइम में तुलना करें — hash_equals, hmac.compare_digest या crypto.timingSafeEqual से।
4. पुराने टाइमस्टैम्प अस्वीकार करें — जैसे पाँच मिनट से पुराने, ताकि रीप्ले हमले रुकें।
5. उसके बाद ही पार्स और प्रोसेस करें — और जल्दी 2xx लौटाएँ।

यह बनावट मानक HMAC पैटर्न पर है; सीक्रेट सर्वर पर रखें और लीक हो तो बदल दें।

कॉलबैक URL चुनना और सुरक्षित रखना

/webhooks/mistket जैसा अलग HTTPS पाथ इस्तेमाल करें, जो सामान्य पेजों से अलग हो, और हर इनवॉइस बनाते समय उसे कॉलबैक URL के रूप में दें। इसे CSRF सुरक्षा, कैशिंग और रीडायरेक्ट से बाहर रखें; 301 रीडायरेक्ट या कैश किया जवाब वेबहुक के चुपचाप फेल होने का आम कारण है। सेशन कुकी न माँगें — गेटवे लॉग-इन यूज़र नहीं है, ऑथेंटिकेशन HMAC सिग्नेचर है। आख़िर में हर डिलीवरी को इवेंट, ऑर्डर ID और रिस्पॉन्स कोड के साथ लॉग करें ताकि "वेबहुक आया या नहीं?" का जवाब सेकंडों में मिल सके।

आइडेम्पोटेंसी: एक ही इवेंट दो बार आ सकता है

अगर आपका एंडपॉइंट टाइमआउट हो या एरर लौटाए, तो गेटवे घंटों तक बढ़ते अंतराल पर दोबारा कोशिश करता है। नेटवर्क की गड़बड़ी भी पहले से प्रोसेस हुआ इवेंट दोबारा ला सकती है। इसलिए हैंडलर आइडेम्पोटेंट होना चाहिए:

• ऑर्डर ID को कुंजी बनाएँ — इनवॉइस जिस ऑर्डर से जुड़ा है उसे खोजें।
• मौजूदा स्टेटस जाँचें — ऑर्डर पहले से पूरा है तो रसीद दें और कुछ न करें।
• ट्रांज़ैक्शन या लॉक इस्तेमाल करें — ताकि दो समानांतर डिलीवरी दोनों प्रोडक्ट न भेजें।
• डिलीवरी ID सेव करें — डुप्लिकेट की जाँच में काम आता है।

इवेंट के आसपास ऑर्डर स्टेटस डिज़ाइन करना

एक आसान स्टेट मशीन ज़्यादातर बग रोकती है: पेंडिंग → कन्फ़र्म हो रहा (paid पर) → पेड (confirmed पर) → पूरा, साथ में कम भुगतान और एक्सपायर की शाखाएँ। सिर्फ़ आगे की ओर बदलाव की अनुमति दें। invoice.confirmed के बाद आया invoice.paid ऑर्डर को कभी पीछे न ले जाए। एक्सपायर इनवॉइस पर देर से आए पेमेंट चुपचाप ऑर्डर खोलने के बजाय समीक्षा के लिए रिकॉर्ड बनाएँ।

मुश्किल स्थितियाँ संभालना

• कम भुगतान — ग्राहक को सटीक बाक़ी रकम बताएँ और कि वह उसी पेमेंट पेज पर भेज सकता है; आंशिक भुगतान जुड़ते जाते हैं।
• ज़्यादा भुगतान — डिलीवर करें, फिर अपनी नीति के अनुसार क्रेडिट या रिफ़ंड ट्रांसफ़र तय करें।
• एक्सपायर — स्टॉक छोड़ें और अगर ग्राहक अब भी ख़रीदना चाहे तो नया इनवॉइस दें।
• गलत नेटवर्क — यह कोड से नहीं, सपोर्ट से सुलझता है; रोकने के लिए चेकआउट पर नेटवर्क साफ़ दिखाएँ।

टेस्टिंग और मॉनिटरिंग

1. टेस्ट एंडपॉइंट खोलें — HTTPS पर, हेडर और रॉ बॉडी लॉग करते हुए।
2. हर इवेंट ट्रिगर करें — छोटे असली पेमेंट से paid, confirmed, underpaid, overpaid और expired।
3. एक डिलीवरी दोहराएँ — पुष्टि करें कि हैंडलर डुप्लिकेट को नज़रअंदाज़ करता है।
4. सिग्नेचर तोड़ें — एक बाइट बदलें और देखें कि अनुरोध अस्वीकार हो।
5. डिलीवरी लॉग देखें — मर्चेंट पैनल हर कोशिश, रिस्पॉन्स कोड और ट्रांज़ैक्शन हैश दिखाता है।
6. फेल होने पर अलर्ट — नॉन-2xx रिस्पॉन्स में उछाल का मतलब है ऑर्डर पूरे नहीं हो रहे।

बॉट और पेड कम्युनिटी भी यही पैटर्न अपनाते हैं; चैट फ़्लो में यह कैसे बैठता है, Telegram बॉट में क्रिप्टो पेमेंट लेना में देखें।

mistKET के साथ वेबहुक

mistKET हर इनवॉइस स्टेटस के लिए HMAC साइन किए वेबहुक भेजता है, फेल डिलीवरी को बढ़ते अंतराल पर दोहराता है और मर्चेंट पैनल में डिलीवरी लॉग, अपेक्षित और प्राप्त रकम व ट्रांज़ैक्शन हैश दिखाता है। API अनुरोध भी इसी तरह साइन होते हैं, इसलिए एक हेल्पर फ़ंक्शन दोनों दिशाएँ संभाल लेता है।

डेवलपर सेक्शन में अनुरोध और वेबहुक के उदाहरण देखें, प्राइसिंग जाँचें और मर्चेंट लॉगिन से की संभालें। एक्सेस के लिए Telegram पर @mistnetwork के ज़रिए आवेदन करें।