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

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

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

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

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

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

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

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

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

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

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

यह गाइड webhook.add से बनाए endpoint के लिए है: सार्वजनिक HTTPS URL और समर्थित इवेंट, जैसे order.processing, order.in_progress, order.completed, order.partial, order.refunded और order.refill_completed। मिला secret सुरक्षित रखें; webhook.list उसे नहीं लौटाता। स्थिति और त्रुटियाँ webhook.list से देखें, endpoint webhook.remove से हटाएँ।

API के जवाब में events array होता है, एक इवेंट होने पर भी। हर इवेंट में id, event, timestamp और data हैं; deliveryId डिलीवरी की पहचान है। छोटा उदाहरण केवल समझाने के लिए है। उसकी पुरानी तारीखें ताज़गी की जाँच में इस्तेमाल न करें।

{
  "events": [
    {
      "id": "EXAMPLE_EVENT_ID",
      "event": "order.completed",
      "timestamp": 1700000000,
      "data": { "order": 7001, "status_key": "completed" }
    }
  ],
  "timestamp": 1700000001,
  "deliveryId": "EXAMPLE_DELIVERY_ID"
}

इवेंट का नाम सत्यापित body से पढ़ें; API बैच को X-Webhook-Event की ज़रूरत नहीं है। Dashboard में बने वेबहुक का एक-इवेंट वाला अलग प्रारूप होता है; दोनों को एक जैसा न मानें।

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

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

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

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

टाइमआउट या 2xx के बाहर जवाब असफल डिलीवरी माना जाता है। NotPanel बढ़ते अंतराल पर प्रयास करता है और लगातार 10 असफलताओं पर API endpoint रोक देता है। सफल डिलीवरी गिनती शून्य करती है। webhook.list देखें; चुप्पी का मतलब बदलाव न होना नहीं है।

अनसुलझे या पुराने ऑर्डर समय-समय पर अधिकतम 100 IDs के बैच में जाँचें और headers व सीमाएँ मानें। रुका रिसीवर ठीक करने के बाद पंजीकरण active होने की पुष्टि करें। पुरानी असफल डिलीवरी अपने-आप फिर आएगी, ऐसा न मानें।

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

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

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

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

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

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

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

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

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

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

X-Webhook-Signature और X-Webhook-Timestamp जाँचें। फिर X-Webhook-Delivery-Id को सत्यापित body के deliveryId से मिलाएँ और events array पढ़ें।

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

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

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