Webhooks

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

यह dAio के अलर्ट और आपकी सूचना प्रणाली के बीच का सेतु है।

सुझाव : एक ही प्रकार की घटना की सदस्यता लेने वाले एकल वेबहुक से शुरू करें, पूरी श्रृंखला को आरंभ से अंत तक सत्यापित करें, फिर विस्तार करें। इस तरह आप प्रसंस्करण को विश्वसनीय बनाने से पहले अपने सिस्टम को सूचनाओं से भर देने से बचेंगे।

एक वेबहुक कॉन्फ़िगर करना

1. सेटिंग्स > वेबहुक पर जाएँ।
2. नया वेबहुक पर क्लिक करें।
3. गंतव्य URL दर्ज करें: आपके सर्वर का HTTPS endpoint (उदा. https://votre-serveur.com/webhook)।
4. संबंधित लेबल पर क्लिक करके सुनने के लिए घटनाएँ चुनें।
5. बनाएँ से पुष्टि करें।

निर्माण के समय स्वचालित रूप से एक secret उत्पन्न होता है। यह प्रत्येक अनुरोध को HMAC-SHA256 से हस्ताक्षरित करने के लिए कार्य करता है (नीचे देखें): इसे सर्वर की ओर सुरक्षित रखें, यह आपको यह सत्यापित करने देता है कि प्रत्येक कॉल वास्तव में dAio से आती है।

चेतावनी : URL HTTPS में होना चाहिए और सार्वजनिक रूप से सुलभ होना चाहिए। सरल HTTP पर या किसी बंद फ़ायरवॉल के पीछे का endpoint डिलीवरी प्राप्त नहीं कर पाएगा।

उपलब्ध घटनाएँ

घटना	विवरण
weather.alert	किसी साइट पर एक मौसम अलर्ट सक्रिय किया गया
weather.threshold	एक कस्टम मौसम सीमा पार की गई
air_quality.alert	एक वायु गुणवत्ता अलर्ट जारी किया गया
pollen.alert	एक पराग अलर्ट जारी किया गया
marine.alert	एक समुद्री स्थिति अलर्ट जारी किया गया
frost.alert	एक पाला अलर्ट सक्रिय किया गया
storm.alert	एक तूफ़ान / आँधी अलर्ट सक्रिय किया गया
business.risk_high	आपकी गतिविधि के लिए एक उच्च जोखिम स्तर का पता चला

सुझाव : प्रत्येक वेबहुक को केवल उन्हीं घटनाओं की सदस्यता दें जो वास्तव में गंतव्य प्रणाली द्वारा उपयोग की जाती हैं। एक « टिकट » endpoint को एक « डैशबोर्ड » endpoint जैसी ही घटनाएँ प्राप्त करने की आवश्यकता नहीं है।

payload का प्रारूप

प्रत्येक डिलीवरी एक POST अनुरोध है जिसका मुख्य भाग एक JSON ऑब्जेक्ट है। सामान्य संरचना इस प्रकार है:

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

event फ़ील्ड घटना के प्रकार की पहचान करता है, timestamp उत्सर्जन का समय दर्शाता है (UTC, ISO 8601 प्रारूप) और data घटना के लिए विशिष्ट विवरण रखता है।

HMAC-SHA256 प्रमाणीकरण

प्रत्येक अनुरोध आपके secret के साथ HMAC-SHA256 के माध्यम से हस्ताक्षरित होता है। हस्ताक्षर X-Daio-Signature हेडर में sha256=<signature> प्रारूप में प्रेषित किया जाता है।

किसी अनुरोध को संसाधित करने से पहले हमेशा इस हस्ताक्षर को सत्यापित करें: यही सुनिश्चित करता है कि कॉल dAio से आती है और payload में परिवर्तन नहीं किया गया है।

सर्वर की ओर सत्यापन (Python):

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

चेतावनी : किसी भी JSON विपटनीकरण (deserialization) से पहले, अनुरोध के कच्चे मुख्य भाग (प्राप्त बाइट्स) पर हस्ताक्षर की गणना करें। ज़रा सा भी पुनर्स्वरूपण hash को बदल देता है और सत्यापन को विफल कर देता है।

परीक्षण और डिबगिंग

• अपने endpoint पर एक काल्पनिक घटना भेजने के लिए किसी वेबहुक के बगल में परीक्षण (▶) आइकन पर क्लिक करें।
• एक 2xx HTTP प्रतिक्रिया पुष्टि करती है कि आपके सर्वर ने अनुरोध प्राप्त किया और स्वीकार किया।
• इसकी हाल की डिलीवरी देखने के लिए वेबहुक का विस्तार करें: HTTP कोड, घटना का प्रकार और टाइमस्टैम्प।
• एक रंगीन बिंदु वेबहुक की स्थिति दर्शाता है: हरा = सक्रिय, लाल = बार-बार विफलताओं के बाद निष्क्रिय।

डिलीवरी का इतिहास

प्रत्येक भेज को लॉग किया जाता है। प्रत्येक प्रयास के लिए, देखने हेतु किसी वेबहुक का विस्तार करें:

• प्रतिक्रिया का HTTP कोड (< 300 होने पर हरा, अन्यथा लाल)
• वितरित घटना का प्रकार
• प्रयास की तिथि और समय

जब डिलीवरी विफल हो जाती हैं तो वेबहुक पर एक विफलता काउंटर प्रदर्शित होता है।

पुनः प्रयास और विश्वसनीयता

dAio विफलता की स्थिति में बढ़ते अंतरालों के साथ स्वचालित रूप से डिलीवरी का पुनः प्रयास करता है। इसलिए आपका endpoint idempotent होना चाहिए: एक ही डिलीवरी कई बार आ सकती है, और आपके प्रसंस्करण को बिना किसी दुष्प्रभाव के वही परिणाम देना चाहिए।

चेतावनी : आपके endpoint को 10 सेकंड से कम में 2xx HTTP कोड के साथ प्रतिक्रिया देनी चाहिए। इसके आगे, या किसी त्रुटि कोड की स्थिति में, डिलीवरी को विफल माना जाता है और इसका पुनः प्रयास किया जाएगा। बार-बार विफलताओं के बाद, वेबहुक स्वचालित रूप से निष्क्रिय कर दिया जाता है।

सर्वोत्तम अभ्यास

• किसी payload को संसाधित करने से पहले हमेशा HMAC हस्ताक्षर सत्यापित करें: किसी अप्रमाणित अनुरोध पर कभी भरोसा न करें।
• तेज़ी से प्रतिक्रिया दें: तुरंत एक 200 लौटाएँ, फिर कार्यभार को पृष्ठभूमि में संसाधित करें। आप टाइमआउट और अनावश्यक पुनः प्रयासों से बचेंगे।
• कई डिलीवरी को सुरक्षित रूप से समाहित करने के लिए अपने प्रसंस्करण को idempotent बनाएँ।
• स्रोत पर फ़िल्टर करें: प्रत्येक वेबहुक को केवल उसकी गंतव्य प्रणाली के लिए उपयोगी घटनाओं की सदस्यता दें।
• किसी endpoint के निष्क्रिय होने से पहले उसकी खराबी का शीघ्र पता लगाने के लिए विफलता काउंटर और डिलीवरी इतिहास पर नज़र रखें।
• किसी वास्तविक घटना की प्रतीक्षा किए बिना श्रृंखला को सत्यापित करने के लिए अपनी ओर से प्रत्येक संशोधन (परिनियोजन, URL परिवर्तन) के बाद परीक्षण बटन का उपयोग करें।

सुझाव : सही जानकारी को स्वचालित रूप से सही सिस्टम तक पहुँचाने के लिए अपने वेबहुक को अलर्ट और अपनी टीम के विन्यास के साथ युग्मित करें। वेबहुक की उपलब्धता आपकी सदस्यता पर निर्भर करती है।