Webhook

मान लीजिए आप एक कपड़ों की ऑनलाइन दुकान चलाते हैं। हर बार जब आप कोई नया उत्पाद जोड़ते हैं, तो कुछ पीछे का काम होता है जिसे आपको खुद हर बार संभालना पड़ता है। जैसे उत्पाद के विवरण का दूसरी भाषा में अनुवाद कर रखना, या जोड़े जाने की सूचना कंपनी के मैसेंजर पर भेजना। इस तरह के पीछे के काम को हर बार हाथ से करने के बजाय, उत्पाद जोड़े जाने के क्षण ही बाहर मौजूद किसी प्रोग्राम को अपने-आप सूचित करके उससे करवाया जा सकता है। यही "कोई घटना होने पर पहले से तय की गई जगह को अपने-आप सूचना देने वाला साधन" Webhook है।

इसकी तुलना दुकान के दरवाज़े पर लगी घंटी से की जा सकती है। जब कोई ग्राहक दरवाज़ा खोलकर अंदर आता है (उत्पाद जोड़ा जाता है), तो घंटी अपने-आप बज जाती है, और अंदर मौजूद कर्मचारी (बाहरी प्रोग्राम) "ग्राहक आ गए" समझकर तुरंत काम पर लग जाता है। किसी को लगातार दरवाज़े के सामने नज़र रखने की ज़रूरत नहीं रहती। Webhook उसी घंटी की तरह, तय की गई घटना घटने के क्षण ही तय की गई जगह पर अनुरोध भेजता है।

इस पृष्ठ पर पहले हम देखेंगे कि Webhook क्या है और इसका उपयोग किन मामलों में होता है, फिर कपड़ों की दुकान के Space में एक Webhook खुद बनाकर देखेंगे। बाहरी प्रोग्राम से लौटे परिणाम को फिर से उत्पाद में भरने वाला WriteBack भी साथ में देखेंगे।

Webhook क्या करता है

Webhook तीन बातें पहले से तय करने से बनता है।

• कब भेजना है: कौन-सी घटना होने पर अनुरोध भेजना है, यह तय करते हैं। उदाहरण के लिए "उत्पाद (Content) नया जोड़ा जाने पर" तय किया जा सकता है।
• कहाँ भेजना है: अनुरोध प्राप्त करने वाले बाहरी प्रोग्राम का पता तय करते हैं। एक इंटरनेट पता (URL) लिख रखते हैं।
• चालू रखना है या बंद: इस Webhook को अभी चालू रखना है (ACTIVE) या कुछ देर के लिए बंद रखना है (INACTIVE), यह तय करते हैं। बंद रखने पर तय की गई घटना घटने पर भी अनुरोध नहीं भेजा जाता।

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

किन बदलावों पर अनुरोध भेजा जाता है

अनुरोध को बुलाने वाली "घटना" Space के अंदर के संसाधनों में होने वाला बदलाव है। उत्पाद जैसे Content, अपलोड की गई फ़ाइल यानी Media, और प्रारूप का ढाँचा यानी Content Type में कुछ घटने पर आप चुन सकते हैं।

हर संसाधन के लिए चुने जा सकने वाले बदलाव इस प्रकार हैं।

उदाहरण के लिए "हर बार उत्पाद नया जोड़े जाने पर अनुरोध भेजो" का मतलब है "उत्पाद (Content) का Create" चुनना।

एक Webhook में कई बदलाव एक साथ भी चुने जा सकते हैं। "उत्पाद जोड़े जाने पर" और "उत्पाद बदले जाने पर" दोनों चुनने पर, इनमें से कोई भी घटना घटे तो अनुरोध जाता है।

शर्त लगाकर दायरा घटाना

चुना गया बदलाव घटने पर भी हमेशा अनुरोध नहीं भेजना चाहते, ऐसा होता है। उदाहरण के लिए "हर Content नहीं, बल्कि 'उत्पाद' प्रारूप से बने Content के जुड़ने पर ही" सूचना चाहिए हो सकती है। ऐसे में फ़िल्टर लगाकर अनुरोध भेजने के मामलों का दायरा घटाते हैं।

एक फ़िल्टर "किसके आधार पर, कैसे तुलना करनी है" यह एक पंक्ति से बनता है। किसके आधार पर छानना है, यह चार में से चुनते हैं।

• किस प्रारूप से बनाई गई वस्तु है: उदाहरण के लिए "उत्पाद" Content Type से बने Content पर ही अनुरोध भेजते हैं। यह सबसे ज़्यादा इस्तेमाल होने वाली शर्त है।
• कोई एक खास वस्तु है: तय की गई उस एक वस्तु में घटे बदलाव पर ही अनुरोध भेजते हैं।
• किसके द्वारा बनाई गई वस्तु है: किसी खास व्यक्ति द्वारा बनाई गई वस्तु पर ही अनुरोध भेजते हैं।
• किसके द्वारा आखिरी बार बदली गई वस्तु है: किसी खास व्यक्ति द्वारा आखिरी बार बदली गई वस्तु पर ही अनुरोध भेजते हैं।

तुलना करने का तरीका भी साथ चुनते हैं। तय किए मान के बराबर होने पर ही, अलग होने पर ही, तय किए कई मानों में से किसी एक के अनुरूप होने पर ही, उनमें से किसी के भी अनुरूप न होने पर ही, या तय किए प्रारूप (पैटर्न) से मेल खाने या न खाने पर ही, इस तरह दायरा घटाया जा सकता है।

कंटेंट स्टूडियो की ट्रिगर सेटिंग में + फ़िल्टर जोड़ें से शर्तें एक-एक पंक्ति करके जोड़ते हैं। कई फ़िल्टर लगाने पर उन सभी शर्तों को पूरा करने वाले मामले में ही अनुरोध जाता है, और एक भी न लगाने पर चुना गया बदलाव घटने पर हर बार अनुरोध जाता है।

बाहरी प्रोग्राम के मनचाहे रूप में भेजना

अलग से तय न करने पर, अनुरोध में बदलाव वाली वस्तु की जानकारी पूरी की पूरी भरकर जाती है। उदाहरण के लिए "Stainless Tumbler 500ml" उत्पाद जोड़े जाने पर, अनुरोध में जाने वाली सामग्री लगभग इस रूप की होती है।

{
  "sys": { "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq", "type": "Content" },
  "fields": {
    "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
  }
}

(असल में इससे ज़्यादा जानकारी भरी जाती है, ऊपर तो केवल एक हिस्सा चुनकर दिखाया गया रूप है।) बाहरी प्रोग्राम इसमें से अपने ज़रूरी मान चुनकर इस्तेमाल कर सकता है। पर कुछ प्रोग्राम ऐसे होते हैं जिनका रूप तय होता है, "इसी रूप में ही लूँगा।" ऐसे में कंटेंट स्टूडियो की पेलोड में Webhook पेलोड कस्टमाइज़ करें चुनकर, भेजने का रूप खुद लिख रखते हैं।

भेजने का रूप लिखते समय, ऊपर के डेटा से मान खींचकर रखने की जगह पर प्लेसहोल्डर का इस्तेमाल करते हैं। प्लेसहोल्डर { /payload/… } रूप का होता है। यहाँ payload ऊपर दिखाई गई उस पूरी वस्तु को इंगित करता है, और उसके बाद वाले पथ से मनचाहा मान ठीक-ठीक चुनते हैं।

• { /payload/sys/id } → ऊपर के डेटा के sys के अंदर का id (उत्पाद का अद्वितीय नंबर)
• { /payload/fields/productName/ko-KR } → fields के अंदर productName का ko-KR (कोरियाई उत्पाद नाम)। fields/ के बाद Field की ID (उत्पाद नाम हो तो productName) और भाषा कोड (कोरियाई हो तो ko-KR) क्रम से लगाते हैं।

उदाहरण के लिए कोई अनुवाद प्रोग्राम कहे कि "अनुवाद करने का लेख और उत्पाद नंबर इस रूप में दो," तो पेलोड इस तरह लिखते हैं।

{
  "id": "{ /payload/sys/id }",
  "text": "{ /payload/fields/productName/ko-KR }"
}

तब टम्बलर उत्पाद के जोड़े जाने के क्षण, प्लेसहोल्डर असली मानों में बदलकर इस तरह भेजे जाते हैं।

{
  "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
  "text": "스테인리스 텀블러 500ml"
}

वही प्लेसहोल्डर भेजने वाले पते (URL) या हेडर मान में भी डाला जा सकता है, और भेजने का तरीका (method) तथा रूप (JSON या फ़ॉर्म रूप) भी साथ चुना जा सकता है। इंगित किए गए पथ पर मान न हो तो वह जगह खाली मान बन जाती है।

बाहरी API key जैसे ऐसे मान जो दूसरों को नहीं दिखने चाहिए, उन्हें हेडर जोड़ते समय उनका टाइप Secret पर सेट कर रखते हैं। तब वह मान छिपाकर सहेजा जाता है और अंतिम उपयोगकर्ता को नहीं दिखता।

मिले जवाब से वापस भरना: WriteBack

भेजे जाने वाले अनुरोध का रूप तय करना अगर पिछला अनुभाग है, तो WriteBack लौटे जवाब को संभालता है। Webhook बाहरी प्रोग्राम को बुलाकर सामान्य (2xx) जवाब पाने पर, उस जवाब को संसाधित करके Space के अंदर के Content या Media को बना सकता है, बदल सकता है, या प्रकाशित-हटा सकता है। इससे परिणाम को इंसान द्वारा कॉपी करके चिपकाने वाली प्रक्रिया खत्म हो जाती है।

कपड़ों की दुकान के अनुवाद उदाहरण को अंत तक देखते हैं। पहले हमने नए उत्पाद का कोरियाई उत्पाद नाम अनुवाद प्रोग्राम को भेजा था। मान लीजिए अनुवाद प्रोग्राम इस तरह जवाब देता है।

{ "translated": "Stainless Tumbler 500ml" }

इस अनुवाद को उसी उत्पाद के अंग्रेज़ी उत्पाद नाम के खाने में भरने वाला WriteBack बनाते हैं। कंटेंट स्टूडियो की WriteBack में + ऑपरेशन जोड़ें से Content की Update (बदलाव) क्रिया एक और जोड़ते हैं और इस तरह तय करते हैं।

• लक्ष्य: अलग से तय न करने पर बदलाव वाला वही उत्पाद (टम्बलर) लक्ष्य बनता है।
• भरने का खाना और भाषा: अंग्रेज़ी उत्पाद नाम होने से खाना है उत्पाद नाम (productName), भाषा है अंग्रेज़ी (en-US)।
• डालने का मान: जवाब के अनुवाद को इंगित करने वाला { /response/translated }।

तब टम्बलर उत्पाद के अंग्रेज़ी उत्पाद नाम का खाना Stainless Tumbler 500ml से भर जाता है।

इस तरह का WriteBack बाहरी LLM से जोड़ने में खास तौर पर काम का है। उदाहरण के लिए उत्पाद विवरण भेजकर बनवाई गई प्रचार छवि को Media के रूप में सहेजना, या बनाए गए परिचय वाक्य से नया Content बनाना, ऐसे प्रवाह एक ही Webhook से बनाए जा सकते हैं।

क्रिया का क्रम

1. बदलाव घटने पर Webhook तय किए रूप में बाहरी प्रोग्राम को अनुरोध भेजता है।
2. जवाब 2xx हो, तो जोड़ी गई WriteBack क्रियाएँ (ऑपरेशन) ऊपर से क्रम से चलाई जाती हैं।
3. हर क्रिया आपस में स्वतंत्र होती है, इसलिए एक के विफल होने पर भी बाकी चलती रहती हैं।
4. WriteBack से हुए बनना-बदलना-हटना-प्रकाशन भी फिर से बदलाव के रूप में पकड़े जाते हैं, और उस बदलाव की सदस्यता लेने वाले दूसरे Webhook को लगातार बुला सकते हैं। अंतहीन घूमने वाला चक्र Webhook बनाते या बदलते समय अपने-आप जाँचा जाकर रोक दिया जाता है।

WriteBack से बनने या बदलने वाले संसाधन का बनाने वाला (createdBy) वही उपयोगकर्ता होता है जिसने वह बदलाव किया था।

मान अभिव्यक्ति

भरने का मान पहले देखे गए वैसे ही प्लेसहोल्डर ({ /… }) से लाते हैं। पर WriteBack में इंगित की जा सकने वाली जड़ें दो हैं।

• केवल एक प्लेसहोल्डर अकेले इस्तेमाल करने पर ({ /response/url }) मान का मूल रूप (अक्षर, संख्या, समूह) जैसा का तैसा लाते हैं।
• अक्षरों के साथ मिलाकर इस्तेमाल करने पर ("बनाया गया: { /payload/sys/id }") एक अक्षर-शृंखला में जुड़ जाता है।
• जवाब JSON नहीं बल्कि सीधे अक्षरों के रूप में आए, तो { /response } से पूरे जवाब को अक्षरों के रूप में लेते हैं (उसके अंदर के उप-पथ इंगित नहीं किए जा सकते)।

Content संभालना ($content)

जवाब से Content बनाने या बदलने वाली क्रिया है। तय करने के आइटम इस प्रकार हैं।

Media संभालना ($media)

जवाब में मिली फ़ाइल को Media के रूप में लाने या Media की स्थिति बदलने वाली क्रिया है।

$media को Content के खाने के मान के रूप में भी इस्तेमाल किया जा सकता है। जवाब में मिली फ़ाइल को Media के रूप में लाने के बाद उस Media को खाने से सीधे जोड़कर, "छवि वाले Content" को एक ही बार में बनाया जा सकता है।

Media का Delete, Archive, Unarchive सूची की जानकारी ही नहीं, बल्कि भंडारण में मौजूद असली फ़ाइल तक को साथ में संभालता है।

सेट करने का तरीका और उदाहरण

कंटेंट स्टूडियो की WriteBack में + ऑपरेशन जोड़ें से क्रियाएँ एक-एक करके जोड़ते हैं। स्क्रीन पर आइटम भरने वाले Visual तरीके और नीचे जैसे writeBacks समूह को सीधे लिखने वाले JSON तरीके के बीच आ-जा सकते हैं। किसी भी तरीके से करें, परिणाम एक ही रहता है।

बाहरी LLM द्वारा बनाई छवि लगाकर नया उत्पाद बनाना। जवाब में भरे छवि पते को Media के रूप में लाकर, उस छवि वाला Content नया बनाते हैं।

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<उत्पाद Content Type sys.id>" } },
        "fields": {
          "productName": "{ /payload/fields/productName/ko-KR }",
          "photo": { "$media": { "source": "{ /response/data/0/url }", "encoding": "Url" } }
        }
      }
    }
  ]
}

बदलाव वाले उसी उत्पाद को समृद्ध करना। target छोड़ने पर बदलाव वाला Content लक्ष्य होता है। जवाब के मान को उस उत्पाद के खाने में भरते हैं।

{
  "writeBacks": [
    {
      "$content": {
        "action": "Update",
        "locale": "en-US",
        "fields": { "productName": "{ /response/translated }" }
      }
    }
  ]
}

जाँच के बाद प्रकाशित करने के लिए सिर्फ़ Draft के रूप में बनाना। publish बंद रखने पर प्रकाशित न करके मसौदे के रूप में छोड़ा जाता है, ताकि इंसान जाँचकर फिर प्रकाशित कर सके।

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<Content Type sys.id>" } },
        "fields": { "text": "{ /response/choices/0/message/content }" },
        "publish": false
      }
    }
  ]
}

जवाब की छवि को स्वतंत्र Media के रूप में लाना। पते से पाने पर encoding को Url रखते हैं, और जवाब में भरे फ़ाइल डेटा से पाने पर Base64 रखते हैं।

{
  "writeBacks": [
    { "$media": { "action": "Create", "source": "{ /response/data/0/url }", "encoding": "Url" } }
  ]
}

Delete, Publish, Unpublish, Archive, Unarchive का रूप एक जैसा है। केवल action और बदले जाने वाला लक्ष्य target लिखने पर उस लक्ष्य की केवल स्थिति बदलती है (लक्ष्य छोड़ने पर बदलाव वाली वही वस्तु)। उदाहरण के लिए जवाब में बताए गए Content को प्रकाशित करना हो तो इस तरह लिखते हैं।

{
  "writeBacks": [
    { "$content": { "action": "Publish", "target": "{ /response/contentId }" } }
  ]
}

कई क्रियाएँ जोड़ने पर वे लिखे क्रम में चलती हैं। "अनुवाद परिणाम को उत्पाद में भरना, फिर प्रचार छवि को Media के रूप में लाना" इस तरह एक के बाद एक रखी जाती हैं।

चलने का परिणाम देखना

हर WriteBack क्रिया का क्या हुआ, यह Webhook के कॉल रिकॉर्ड में देखते हैं। हर क्रिया के लिए निम्नलिखित दर्ज होता है।

सफल क्रिया को परिणाम ID से इस तरह देखा जा सकता है कि कौन-सा संसाधन बना या बदला। जवाब 2xx न हो तो WriteBack बिलकुल नहीं चलता, इसलिए परिणाम रिकॉर्ड भी खाली रहता है।

जान रखने योग्य बातें

• अनुरोध भेजने वाला बदलाव केवल एक हो। एक Webhook "जोड़ना (Create)" और "प्रकाशन (Publish)" को एक साथ पकड़े, तो बाहरी प्रोग्राम दो बार बुलाया जा सकता है। WriteBack इस्तेमाल करने वाला Webhook केवल एक बदलाव चुनें।
• केवल मान खिसकाता है, गणना नहीं कर सकता। जवाब से मान निकालकर डालने तक ही करता है, शर्त-शाखा या दोहराव जैसा प्रसंस्करण नहीं करता।
• दोबारा कोशिश नहीं करता। प्रसंस्करण के बीच में समस्या होने पर वह क्रिया वैसे ही नष्ट हो सकती है।
• जैसे-तैसे न बने इसका ध्यान। केवल WriteBack से ही बनने वाले Content Type को सामान्य उपयोगकर्ता सीधे न बना पाए, इसके लिए अनुमति का दायरा घटाकर रखना अच्छा है।

कपड़ों की दुकान का Webhook बनाना

अब कपड़ों की दुकान के Space में एक Webhook बनाकर देखते हैं। यह "नया उत्पाद जोड़े जाने पर, पहले से तैयार बाहरी अनुवाद प्रोग्राम को उस बात की सूचना देता है" वाला Webhook है। अनुरोध पाने वाले बाहरी प्रोग्राम का पता https://example.com/translate मानते हैं।

1. कपड़ों की दुकान के Space की सेटिंग में Webhook स्क्रीन खोलें।
2. ऊपर दाईं ओर का बनाएं बटन दबाएँ।
3. नाम के खाने में नई उत्पाद अनुवाद सूचना दर्ज करें। यह नाम बाद में पहचानने के लिए है कि यह कौन-सा Webhook है।
4. अनुरोध भेजने वाला बदलाव तय करें। केवल किसी खास बदलाव पर भेजने के लिए विशिष्ट ट्रिगर घटनाएँ चुनें चुनकर मनचाहा बदलाव (यहाँ उत्पाद (Content) का Create) निर्दिष्ट करें, और हर बदलाव पर भेजने के लिए सभी घटनाओं के लिए ट्रिगर करें चुनें।
5. URL के खाने में अनुरोध पाने वाले बाहरी प्रोग्राम का पता https://example.com/translate दर्ज करें।
6. सक्रिय चालू रखने पर बनते ही अनुरोध भेजा जाता है (ACTIVE)। थोड़ी देर सिर्फ़ परीक्षण करना हो तो बंद रखें (INACTIVE)।
7. बनाएं बटन दबाकर Webhook बनाएँ।

सूची में नई उत्पाद अनुवाद सूचना ACTIVE स्थिति में दिखाई दे, तो Webhook बन चुका है।

बनाने के बाद कपड़ों की दुकान में सचमुच एक नया उत्पाद जोड़कर देखें। जोड़ने के क्षण Webhook लिख रखे पते पर अनुरोध भेजता है। अनुरोध ठीक से गया या नहीं, बाहरी प्रोग्राम ने कैसे जवाब दिया, यह Webhook के कॉल रिकॉर्ड में देखा जा सकता है।

चालू-बंद करना और बदलना

Webhook को बनाने के बाद भी कभी भी चालू-बंद किया जा सकता है। कुछ देर अनुरोध रोकना हो तो मिटाने के बजाय INACTIVE करके बंद रखें। बंद रहने के दौरान नया उत्पाद जोड़ने पर भी अनुरोध नहीं जाता। फिर से ACTIVE करने पर उसी क्षण से दोबारा अनुरोध भेजना शुरू होता है।

बनाए गए Webhook को दोबारा खोलने पर सक्रिय बंद या दोबारा चालू किया जा सकता है। नाम, अनुरोध भेजने का पता, बुलाने वाला बदलाव जैसी सामग्री भी बाद में बदली जा सकती है, और जो Webhook अब इस्तेमाल नहीं होता उसे मिटा सकते हैं।

आगे क्या करें

• Content मॉडलिंग: Webhook जिस लक्ष्य पर अनुरोध बुलाता है, उस "उत्पाद" जैसे Content का प्रारूप ढाँचा बनाने का तरीका बताता है।
• Content लिखना: असली उत्पाद जोड़कर Webhook के चलने की जाँच कर सकते हैं।
• API रेफ़रेंस: Webhook को प्रोग्राम से सीधे बनाने और प्रबंधित करने में इस्तेमाल होने वाले अनुरोध-जवाब के रूप और Field विवरण को बताता है।