वेबहुक या पोलिंग? ऐसा ऑर्डर ट्रैकर बनाएँ जो छूटी जानकारी वापस पा सके

आम बदलावों के लिए वेबहुक और अपने रिकॉर्ड का पैनल से मिलान करने के लिए स्टेटस जाँच रखें। भरोसेमंद सार्वजनिक रिसीवर तैयार नहीं है तो बैच में पोलिंग से शुरू करें।

ऐप दोबारा शुरू होते समय ऑर्डर पूरा हो सकता है। जवाब की पुष्टि खोने पर इवेंट दो बार आ सकता है। ट्रैकर को दोनों स्थितियाँ संभालनी चाहिए, ताकि पुरानी जानकारी न दिखे और एक अपडेट दो बार लागू न हो।

हर तरीके का काम तय करें

पोलिंग: अभी की स्थिति पूछें

action=status जाँच के समय की स्थिति देता है। एक अनुरोध में अधिकतम 100 IDs भेज सकते हैं। जल्दी-जल्दी पूछने पर अधिक अनुरोध लगेंगे, भले कुछ बदला न हो।

वेबहुक: चुने गए बदलाव पाएँ

NotPanel आपकी HTTPS URL पर इवेंट भेजता है। यह क्लाइंट की status अनुरोध सीमा नहीं लेता, पर रिसीवर को पर्याप्त क्षमता और निगरानी चाहिए।

रिकॉर्ड मिलान: छूटी जानकारी सुधारें

रुकावट या पुराने रिकॉर्ड के बाद संबंधित ऑर्डर जाँचें। इवेंट छूट सकते हैं, दोबारा प्रयास सीमित हैं और पहुँचने का समय निश्चित नहीं है।

NotPanel API क्या भेजती है

Endpoint अपने dashboard के API पेज पर या webhook.add से जोड़ें: सार्वजनिक HTTPS URL और ज़रूरी इवेंट, जैसे order.processing, order.in_progress, order.completed, order.partial, order.canceled, order.cancel_refused, refill.completed और refill.rejected; वेबहुक रेफ़रेंस में पूरी सूची है। secret सुरक्षित रखें: वह केवल एक बार दिखता है और webhook.list उसे कभी नहीं लौटाता। अपने endpoints webhook.list से देखें, webhook.test से टेस्ट ping भेजें और endpoint webhook.remove से हटाएँ।

हर डिलीवरी में एक ही इवेंट एक छोटे लिफ़ाफ़े में आता है: id, type, schema_version, created_at, sequence और data। data.order में वही फ़ील्ड होते हैं जो action=status के जवाब में होते हैं। नीचे का छोटा उदाहरण केवल ढाँचा दिखाता है, असली ऑर्डर नहीं।

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

इवेंट का प्रकार सत्यापित body से पढ़ें। X-Webhook-Event भी भेजा जाता है, पर उस पर हस्ताक्षर नहीं होता। Dashboard और API से जोड़े गए endpoints को एक जैसा लिफ़ाफ़ा मिलता है।

इवेंट सुरक्षित तरीके से लें

1. मूल body रखें। secret और X-Webhook-Timestamp से X-Webhook-Signature जाँचें और अपनी तय समय-सीमा लागू करें। body दोबारा बनाने पर हस्ताक्षर वाले bytes बदल सकते हैं।
2. प्रयासों को ट्रैक करने के लिए X-Webhook-Delivery-Id लॉग करें; उस डिलीवरी के हर दोबारा प्रयास में यह वही रहता है। 2xx देने से पहले सत्यापित इवेंट सहेजें। सुरक्षित स्वीकार नहीं कर सकते तो दोबारा प्रयास होने दें।
3. हर इवेंट id एक बार लागू करें। दोहराव की पहचान ऐप दोबारा शुरू होने पर भी बनी रहे और ऑर्डर अपडेट के साथ सुरक्षित हो। एक ही इवेंट id उस इवेंट से जुड़े हर endpoint तक पहुँचता है।
4. धीमा काम स्वीकार करने के बाद करें। हस्ताक्षर असलियत बताता है, पहुँचने का क्रम नहीं। इवेंट को क्रम में रखने के लिए sequence इस्तेमाल करें; देर का इवेंट नई स्थिति से टकराए तो बदलने से पहले status जाँचें।

हस्ताक्षर जाँचने की गाइड

रिसीवर उपलब्ध न हो तो क्या होगा?

टाइमआउट (10 सेकंड) या 2xx के बाहर जवाब एक असफल प्रयास है। NotPanel हर डिलीवरी 24 घंटे में अधिकतम 8 बार भेजता है: तुरंत, फिर इवेंट के 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे, 12 घंटे और 24 घंटे बाद। लगातार 50 असफलताओं या 3 दिन तक एक भी सफलता न मिलने पर endpoint रोक दिया जाता है और खाते के मालिक को सूचना मिलती है। सफल डिलीवरी गिनती शून्य करती है। webhook.list देखें; चुप्पी का मतलब बदलाव न होना नहीं है।

अनसुलझे या पुराने ऑर्डर समय-समय पर अधिकतम 100 IDs के बैच में जाँचें और headers व सीमाएँ मानें। रिसीवर ठीक करने के बाद dashboard के API पेज के वेबहुक सेक्शन में endpoint फिर चालू करें; इससे उसकी असफलता गिनती शून्य हो जाती है। चाहें तो उसे webhook.remove से हटाकर सही HTTPS URL और चुने हुए events के साथ webhook.add से फिर जोड़ें, नया secret सुरक्षित रखें और रिसीवर की जाँच में वही लगाएँ। सार्वजनिक API में endpoint फिर चालू करने की कोई action नहीं है। रुकने के समय कतार में रही डिलीवरी दोबारा नहीं भेजी जातीं, इसलिए छूटे ऑर्डर की स्थिति status से मिलाएँ।

सिर्फ सफल डिलीवरी से आगे जाँचें

नमूना संदेश और अपना टेस्ट secret इस्तेमाल करें; ग्राहक के असली ऑर्डर आवश्यक नहीं हैं।

• एक डिलीवरी दो बार आए तो एक ही अपडेट हो।
• एक ही इवेंट दो बार आए और बीच में ऐप दोबारा शुरू हो, फिर भी उसे पहचाना जाए।
• एक byte बदले या पुराना समय हो तो आपकी नीति के अनुसार जाँच असफल हो।
• रुकावट और देर के इवेंट के बाद status वर्तमान जानकारी वापस दे।

चुने हुए इवेंट, secret की जाँच और जल्दी पुष्टि की सलाह GitHub की वेबहुक गाइड में भी है. यहाँ दिए headers, प्रारूप और दोबारा प्रयास की सीमाएँ NotPanel की हैं।

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

क्या केवल पोलिंग कर सकते हैं?

हाँ। बैच में जाँचें और संख्या व सीमा के हिसाब से अंतराल रखें। ऑर्डर बनाने या देखने के लिए वेबहुक अनिवार्य नहीं हैं।

क्या वेबहुक तुरंत और केवल एक बार आता है?

नहीं। देर या दोहराव हो सकता है। हर डिलीवरी सत्यापित करें, हर इवेंट एक बार लागू करें और छूटी जानकारी के लिए status जाँच रखें।

कौन से headers जाँचें?

X-Webhook-Signature और X-Webhook-Timestamp जाँचें। फिर सत्यापित body से id, type और data पढ़ें। X-Webhook-Delivery-Id केवल प्रयास ट्रैक करने के लिए इस्तेमाल करें।

क्या वेबहुक अनिश्चित add को सुरक्षित बनाता है?

दोनों अलग समस्याएँ हैं। add दोहराते समय मूल request_id और बिना बदले पैरामीटर रखें, फिर मिली ऑर्डर ID सहेजें।

संदर्भ: वेबहुक के नियम · ऑर्डर स्टेटस · टाइमआउट रिकवरी.