वेबहुक क्या है? घटनाएँ, वितरण, सुरक्षा और डिज़ाइन

स्क्रैपलेस स्क्रैपिंग एपीआई एक कॉन्फ़िगर किए गए वेबहुक यूआरएल पर एक HTTP POST अनुरोध भेज सकता है, जब एक असिंक्रोनस स्क्रैपिंग कार्य पूरा होता है।

वेबहुक क्या है?

एक वेबहुक एक तंत्र है जिसके माध्यम से एक प्रणाली किसी अन्य प्रणाली को एक HTTP अनुरोध भेजती है जब एक इवेंट होता है। प्राप्त करने वाला एप्लिकेशन एक एंडपॉइंट यूआरएल पंजीकृत करता है और अक्सर ऐसे इवेंट प्रकारों का انتخاب करता है जैसे कार्य पूरा हुआ, चालान का भुगतान हुआ, रिकॉर्ड अपडेट हुआ, तैनाती समाप्त हो गई, या संदेश वितरित हुआ। जब इवेंट होता है, तो उत्पादक उस एंडपॉइंट को इवेंट डेटा और मेटाडेटा के साथ कॉल करता है।

एक वेबहुक को कभी-कभी एक रिवर्स एपीआई कॉल के रूप में वर्णित किया जाता है। एक सामान्य एपीआई इंटरैक्शन में, उपभोक्ता स्थिति को पढ़ने या बदलने के लिए एक अनुरोध प्रारंभ करता है। एक वेबहुक के साथ, उत्पादक उपभोक्ता को सूचित करने के लिए एक अनुरोध प्रारंभ करता है। प्राप्त करने वाला यूआरएल अभी भी एक HTTP एंडपॉइंट है, और कार्यान्वयन को सामान्य एपीआई सुरक्षा, लगाम, उपलब्धता, और अवलोकन प्रथाओं को लागू करना चाहिए।

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

एक वेबहुक कैसे काम करता है

1. उपभोक्ता एक एंडपॉइंट पंजीकृत करता है। पंजीकरण एक डैशबोर्ड या एपीआई में हो सकता है और आमतौर पर सदस्यता के साथ एक रहस्य को जोड़ता है।
2. उपभोक्ता इवेंट का चयन करता है। संकरा सदस्यता अनावश्यक ट्रैफ़िक और डेटा एक्सपोज़र को कम करती है।
3. उत्पादक एक इवेंट को रिकॉर्ड करता है। एक डोमेन क्रिया एक स्थिर पहचानकर्ता के साथ एक अपरिवर्तनीय इवेंट या वितरण कार्य बनाती है।
4. उत्पादक पेलोड बनाता है। यह एक इवेंट प्रकार, इवेंट आईडी, घटना का समय, स्कीमा संस्करण, और प्रासंगिक डेटा को अनुक्रमित करता है।
5. उत्पादक वितरण को साइन करता है। सिग्नेचर कच्चे शरीर और ताजगी मेटाडेटा को दस्तावेजित स्कीम के तहत कवर करता है।
6. उत्पादक एक HTTP अनुरोध भेजता है। JSON शरीर के साथ POST सामान्य है, लेकिन अनुबंध विधि और मीडिया प्रकार को निर्धारित करता है।
7. उपभोक्ता इसे सत्यापित और रिकॉर्ड करता है। एंडपॉइंट परिवहन, सिग्नेचर, टाइमस्टैम्प, इवेंट आईडी, स्कीमा, और सदस्यता की जांच करता है पहले कि इवेंट को स्वीकार किया जा सके।
8. उपभोक्ता स्वीकृत करता है। यह दीर्घकालिक स्वीकृति के बाद दस्तावेजित सफलता स्थिति लौटाता है और एक कतार या श्रमिक के माध्यम से लंबे समय तक प्रोसेसिंग करता है।

वेबहुक पेलोड उदाहरण

एक छोटा इवेंट लिफाफा डोमेन डेटा से मेटाडेटा को अलग कर सकता है:

{
  "id": "evt_7f32",
  "type": "task.completed",
  "occurred_at": "2026-08-24T03:10:00Z",
  "version": "1",
  "data": {
    "task_id": "task_b18c",
    "status": "completed"
  }
}

दिखाई गई तारीख एक प्रशंसात्मक कोड स्थिरांक है न कि एक प्रकाशन स्टाम्प। इवेंट आईडी डिडुप्लीकेशन का समर्थन करता है, प्रकार हैंडलर और स्कीमा को चुनता है, घटना का समय डोमेन इवेंट का वर्णन करता है, और संस्करण पेलोड विकास को नियंत्रित करता है। वितरण का समय अनुरोध के मेटाडेटा में आता है जब सिग्नेचर स्कीम इसका उपयोग करती है।

यह मान न रखें कि एक वेबहुक बॉडी पूर्ण वर्तमान संसाधन को शामिल करता है। कुछ उत्पादक एक आईडी के साथ एक पतली सूचना भेजते हैं, जिसके बाद उपभोक्ता एपीआई को अधिकृत वर्तमान स्थिति प्राप्त करने के लिए कॉल करता है। अन्य एक पूर्ण इवेंट स्नैपशॉट भेजते हैं। अनुबंध को यह बताना चाहिए कि क्या पेलोड इवेंट का प्रतिनिधित्व करता है, इवेंट के बाद संसाधन, या एक प्वाइंटर।

वेबहुक बनाम पोलिंग, एपीआई, और वेबSocket

महत्वपूर्ण सिस्टम अक्सर पैटर्न को संयोजित करते हैं। एक वेबहुक तेज़ सूचना प्रदान करता है, जबकि एक निर्धारित सामंजस्य प्रक्रिया वर्तमान API स्थिति की तुलना स्थानीय स्थिति से करती है। वेबहुक विलंबता में सुधार करता है; सामंजस्य गैप या नीति परिवर्तनों का पता लगाता है बिना यह मानकर कि एक डिलीवरी पथ सही है।

वेबहुक सिग्नेस कैसे काम करते हैं

एक साझा-गुप्त डिज़ाइन सामान्यतः सटीक कच्चा अनुरोध शरीर और मेटाडेटा जैसे डिलीवरी टाइमस्टैम्प और इवेंट आईडी पर एक कीड 해श का उपयोग करता है। HMAC संदेश प्रमाणन के लिए एक मानक निर्माण है, जो परिभाषित है RFC 2104. अन्य प्रदाता विषम सिग्नेचरों का उपयोग करते हैं ताकि उपभोक्ता सार्वजनिक कुंजी के साथ सत्यापित कर सकें।

उपभोक्ता को प्रदाता के बाइट-फॉर-बाइट एल्गोरिदम का पालन करना चाहिए। सिग्नेचर हेडर को इसके संस्करणित प्रारूप के अनुसार पार्स करें, सिग्नेड सामग्री को सही रूप से पुनर्निर्माण करें, अपेक्षित मूल्य की गणना करें, और निरंतर-समय फ़ंक्शन के माध्यम से तुलना करें। केवल सत्यापन के बाद ही कोड JSON पेलोड को पार्स और विश्वसनीय करना चाहिए।

फ्रेमवर्क मिडलवेयर सत्यापन को तोड़ सकता है जब यह JSON को पार्स करता है और इसे फिर से संग्रहीत करता है। व्हाइटस्पेस, प्रॉपर्टी क्रम, एस्केपिंग, और संख्या प्रारूपण बदल सकते हैं भले ही डेटा समान दिखता हो। सामान्य शरीर पार्सिंग से पहले कच्चे शरीर के बाइट कैप्चर करें, फिर सत्यापित बाइट्स को JSON पार्सर को पास करें।

पुनरावृत्ति सुरक्षा और आइडेम्पोटेंसी

यदि सिग्नेचर कभी समाप्त नहीं होता है तो एक मान्य पुराना वेबहुक दुर्भावनापूर्ण तरीके से पुनः चलाया जा सकता है। सिग्नेचर योजनाएँ इसलिए एक डिलीवरी टाइमस्टैम्प या किसी अन्य ताजगी मान को शामिल करती हैं। रिसीवर केवल एक छोटा दस्तावेजित समय खिड़की स्वीकार करता है और अपनी घड़ी को समन्वयित रखना चाहिए। टाइमस्टैम्प जांच घटना-ID डिडुप्लिकेशन को पूरक करती है, न कि इसे प्रतिस्थापित करती है।

आइडेम्पोटेंसी का मतलब है कि एक ही तार्किक इवेंट को एक से अधिक बार प्रोसेस करने पर वही व्यावसायिक परिणाम उत्पन्न होता है जैसे इसे एक बार प्रोसेस करना। उत्पादक के स्थिर इवेंट आईडी को एक तालिका में अद्वितीयता बाधा के साथ संग्रहीत करें, सबसे अच्छा उस व्यवसाय परिवर्तन के लिए उसी लेनदेन में। एक इवेंट को “देखा” चिह्नित करना व्यवसाय अपडेट से पहले काम को खो सकता है यदि प्रक्रिया उन कार्यों के बीच रुकती है।

कुछ संचालन स्वाभाविक रूप से आइडेम्पोटेंट होते हैं, जैसे कि एक रिकॉर्ड की स्थिति को एक विशिष्ट संस्करण पर सेट करना। अन्य, जैसे कि बैलेंस बढ़ाना या संदेश भेजना, इवेंट आईडी से जुड़े आइडेम्पोटेंसी रिकॉर्ड की आवश्यकता होती है। उत्पादक के दस्तावेजित पहचानकर्ता द्वारा डिडुप्लिकेट करें, पेलोड को हैश करके नहीं, क्योंकि दो वैध इवेंट्स के समान शरीर हो सकते हैं।

क्रमबद्धता और इवेंट संस्करण

डिलीवरी क्रम घटना के होने के क्रम से भिन्न हो सकता है क्योंकि घटनाएँ अलग-अलग श्रमिकों, क्षेत्रों, या कतारों के माध्यम से यात्रा कर सकती हैं। एक नया अपडेट एक पुराने से पहले आ सकता है। उपभोक्ताओं को यह नहीं मानना चाहिए कि आगमन का क्रम व्यवसाय का क्रम है जब तक कि उत्पादक इसे सदस्यता के लिए स्पष्ट रूप से सुनिश्चित न करे।

परिभाषित शब्दार्थ के साथ एक संसाधन संस्करण, अनुक्रम, या इवेंट होने का समय शामिल करें। केवल तभी स्थिति अपडेट लागू करें जब इसका संस्करण स्थानीय संस्करण से नया हो। घटनाओं के लिए जो स्थायी कार्यों का प्रतिनिधित्व करते हैं न कि स्थिति स्नैपशॉट, क्षेत्र द्वारा स्थापित इवेंट अनुक्रम नियमों को बनाए रखें।

स्कीमा संस्करण संसाधन संस्करण से अलग है। स्कीमा संस्करण पेलोड के आकार का वर्णन करता है; संसाधन संस्करण किसी विशेष इकाई की स्थिति का वर्णन करता है। अवधारणाओं को अलग रखना एक पेलोड-फॉर्मट परिवर्तन को नए व्यावसायिक रिकॉर्ड की तरह प्रकट होने से रोकता है।

पहले स्वीकार करें, एक कतार के माध्यम से प्रोसेस करें

एक वेबहूक एंडपॉइंट को सीमित काम करना चाहिए: अनुरोध के आकार को लागू करें, सिग्नेचर की जांच करें, लिफाफा मान्य करें, इवेंट आईडी को आरक्षित करें, स्वीकृत इवेंट को संग्रहीत या कतारबद्ध करें, और दस्तावेजित सफलता प्रतिक्रिया लौटाएँ। धीमे डेटाबेस जुड़नार, बाहरी API कॉल, फ़ाइल निर्माण, और ईमेल भेजना श्रमिकों में होना चाहिए।

दृढ़ स्वीकृति महत्वपूर्ण है। इवेंट रेकॉर्ड होने से पहले सफलता लौटाने से काम खो सकता है यदि प्रक्रिया रुक जाती है। प्रतिक्रिया करने से पहले प्रत्येक डाउनस्ट्रीम कार्रवाई का इंतजार करने से उत्पादक को एक संबंध बनाए रखना पड़ता है और जब एंडपॉइंट अपनी प्रतिक्रिया समय सीमा को पार करता है तब पुनरावृत्त डिलीवरी हो सकती है।

कतार संदेश को सत्यापित इवेंट, सदस्यता संदर्भ, और सुरक्षित ट्रेसिंग पहचानकर्ताओं को शामिल करना चाहिए। सिग्नेचर सत्यापन के लिए उपयोग किए गए रहस्यों को कतार पेलोड में नहीं होना चाहिए।

एंडपॉइंट पंजीकरण सुरक्षा

यदि उपयोगकर्ता मनमाने वेबहुक URL पंजीकृत कर सकते हैं, तो उत्पादक एक HTTP क्लाइंट बन जाता है जो उपयोगकर्ता इनपुट पर कार्य कर रहा है। सिस्टम को सर्वर-साइड अनुरोध धोखाधड़ी के खिलाफ सुरक्षा करनी चाहिए। OWASP SSRF रोकथाम धोखाधड़ी पत्रिका अनुमति सूची और नेटवर्क-स्तरीय नियंत्रणों का वर्णन करता है।

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

पंजीकरण के दौरान एंडपॉइंट स्वामित्व की पुष्टि एक चुनौती या हस्ताक्षरित हैंडशेक के माध्यम से करें। वेबहूक प्रतिक्रिया शरीर को अविश्वसनीय मानें और डिलीवरी त्रुटि संदेशों के माध्यम से आंतरिक नेटवर्क विवरण को उजागर न करें।

सामान्य वेबहूक उपयोग के मामले

पर्यवेक्षण और संचालन

इवेंट आईडी, सदस्यता आईडी, इवेंट प्रकार, स्कीमा संस्करण, प्राप्त समय, सत्यापन निर्णय, स्वीकृति स्थिति, प्रसंस्करण स्थिति, और सुरक्षित सहसंबंध पहचानकर्ताओं का ट्रैक करें। हस्ताक्षरित रहस्यों, पूर्ण स्वीकृति प्रसंस्करण हेडर, या संवेदनशील पेलोड फ़ील्ड्स को लॉग में न रखें।

स्वीकृति की देरी, कतार में देरी, प्रसंस्करण की अवधि, डुप्लिकेट दर, हस्ताक्षर की विफलताएँ, अमान्य स्कीमा, पुरानी टाइमस्टैम्प, और क्रम का संघर्ष मापें। एक स्वीकार किए गए इवेंट को जो बाद में विफल हो जाता है, उसे सामान्य सफलता मीट्रिक में न गुम होने दें।

एक नियंत्रित प्रशासनिक दृश्य प्रदान करें जो इवेंट आईडी द्वारा खोज कर सके और लालटेन वितरण इतिहास दिखा सके। संचालन टीमों को एक लापता स्थिति परिवर्तन का निदान करने के लिए पर्याप्त सबूत की आवश्यकता होती है बिना क्रेडेंशियल या पूर्ण संवेदनशील बॉडी को उजागर किए।

वेबहुक डिजाइन चेकलिस्ट

1. स्थिर इवेंट प्रकार और आईडी को परिभाषित करें। यह दस्तावेज करें कि पेलोड घटनाएँ, स्नैपशॉट, या प्वाइंटर्स हैं।
2. स्कीमा का संस्करण निर्धारित करें। नए वैकल्पिक फ़ील्ड और इवेंट संशोधनों के लिए संगतता नियम बताएं।
3. कच्चे बाइट्स और ताजगी मेटाडेटा पर हस्ताक्षर करें। सटीक सत्यापन चरण प्रकाशित करें और रहस्यों का प्रतिस्थापन समर्थन करें।
4. एंडपॉइंट सुरक्षा लागू करें। स्वामित्व सत्यापित करें और SSRF स्थलों को ब्लॉक करें।
5. आइडेम्पोटेंटली स्वीकार करें। एक अद्वितीय इवेंट आईडी और लेनदेन के लिए सुरक्षित डीडुप्लीकेशन रिकॉर्ड का उपयोग करें।
6. स्थायी स्वीकृति के बाद स्वीकार्यता ज्ञापित करें। लंबे कार्य को कतार में रखें।
7. दोहराव और पुनर्व्यवस्था की अपेक्षा करें। आवश्यकता क्रम मान्यताओं के बजाय संसाधन संस्करण और समन्वयण का उपयोग करें।
8. पर्यवेक्षण डेटा को लालित करें। लॉग और समर्थन उपकरणों से रहस्यों और संवेदनशील पेलोड फ़ील्ड्स को बाहर रखें।

निष्कर्ष

एक वेबहुक एक इवेंट को HTTP सूचना में बदलता है, संपूर्ण हिंड देना बिना निरंतर पुलिंग के। HTTP कॉल आसान भाग है। एक उत्पादन डिज़ाइन कच्चे-बॉडी हस्ताक्षरों का सत्यापन करता है, ताजगी लागू करता है, इवेंट आईडी द्वारा डेडुप्लिकेट करता है, पुनर्व्यवस्था को संभालता है, स्थायी स्वीकृति के बाद ही स्वीकार करता है, कतार के माध्यम से प्रसंस्करण करता है, एंडपॉइंट रजिस्ट्रेशन को SSRF से सुरक्षित करता है, और महत्वपूर्ण स्थिति को समायोजित करता है। ये नियंत्रण एक कॉलबैक को एक विश्वसनीय एकीकरण सीमा में बदलते हैं।