Webhook

Webhook एक ऐसी सेटिंग है जो Space में कोई घटना होने पर (उदाहरण के लिए Content का बनना या प्रकाशन) पहले से तय की गई कार्रवाई अपने आप चलाती है। कार्रवाई दो में से एक होती है: यह किसी बाहरी URL पर HTTP अनुरोध भेजती है (url), या Space के अंदर किसी Script को चलाती है (script)। इसका उपयोग बाहरी सिस्टम के एकीकरण या स्वचालन के लिए होता है। उदाहरण के लिए, इसे इस प्रकार कॉन्फ़िगर किया जा सकता है कि जब भी कोई उत्पाद Content प्रकाशित हो, यह कंपनी के अंदरूनी सूचना सर्वर को कॉल करे, या किसी पहले से तय किए गए Script से आगे का कार्य चलाए।

url और script में से ठीक एक को निर्दिष्ट करें। दोनों निर्दिष्ट करने पर, या दोनों खाली छोड़ने पर, अनुरोध अस्वीकृत हो जाता है। Webhook CMA में Space का अधीनस्थ संसाधन है, और इसका पथ /spaces/{spaceId}/webhooks को आधार मानता है।

संसाधन संरचना

नीचे Webhook "उत्पाद परिवर्तन सूचना" की एकल पठन प्रतिक्रिया दी गई है। यह sys (सिस्टम गुण) के साथ-साथ भेजने का लक्ष्य, सदस्यता वाली घटनाएँ, और ट्रिगर शर्त जैसी सेटिंग फ़ील्ड रखता है।

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PWhk01Examp",
    "type": "Webhook",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T11:30:00.000Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T11:30:00.000Z",
    "version": 1
  },
  "name": "उत्पाद परिवर्तन सूचना",
  "filters": [
    { "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }
  ],
  "headers": [
    { "key": "X-Source", "value": "weegloo", "secret": false }
  ],
  "basicAuth": { "username": "dailywear" },
  "topics": ["Content.Create", "Content.Publish"],
  "transformation": { "method": "POST", "contentType": "application/json", "includeBody": true },
  "url": "https://api.dailywear.example/webhooks/products",
  "activate": true,
  "runAs": "HookOwner"
}

मुख्य कुंजियाँ:

• sys.id: Webhook का अद्वितीय पहचानकर्ता। यह एकल पठन, संशोधन, और विलोपन पथ के {webhookId} में जाता है।
• url: घटना होने पर कॉल किया जाने वाला बाहरी लक्ष्य URL। इसे और script को मिलाकर ठीक एक निर्दिष्ट करें।
• script: बाहरी कॉल के बजाय चलाए जाने वाले Script का संदर्भ। इसे और url को मिलाकर ठीक एक निर्दिष्ट करें। ऊपर के उदाहरण में यह नहीं है। नीचे url और script (ठीक एक) में बताया गया है।
• runAs: script जिस उपयोगकर्ता पहचान के रूप में चलता है। नीचे runAs में बताया गया है।
• topics: किन घटनाओं की सदस्यता लेनी है, यह तय करने वाला सरणी (array)। प्रारूप नीचे topics में बताया गया है।
• filters: सदस्यता वाली घटनाओं में से वास्तव में किन्हें ट्रिगर करना है, इसकी शर्तें। नीचे filters में बताया गया है।
• transformation: url पर बाहर जाने वाले अनुरोध के स्वरूप (मेथड, बॉडी आदि) को बदलने वाली सेटिंग। नीचे transformation में बताया गया है।

सिस्टम गुण (sys)

हर Webhook सामान्य सिस्टम गुणों को sys ऑब्जेक्ट में रखता है। space, createdBy, और updatedBy Refer स्वरूप ({ "sys": { "id", "type": "Refer", "targetType" } }) में आते हैं।

Webhook एक सेटिंग संसाधन है, इसलिए इसमें प्रकाशन की अवधारणा नहीं है। Content या Content Type के विपरीत इसमें publish, archive, status जैसे प्रकाशन-स्थिति गुण नहीं होते, केवल परिवर्तन ट्रैक करने वाला version होता है। चालू और बंद करना प्रकाशन से नहीं, बल्कि बॉडी फ़ील्ड activate से नियंत्रित होता है।

बॉडी गुण

Webhook की बॉडी (बनाते और संशोधित करते समय भेजे जाने वाले, और प्रतिक्रिया में लौटने वाले सेटिंग मान) निम्न फ़ील्ड से बनी होती है।

△ चिह्नित url और script में से आप ठीक एक को निर्दिष्ट करते हैं। दोनों निर्दिष्ट करने पर, या दोनों खाली छोड़ने पर, अनुरोध अस्वीकृत हो जाता है।

headers का हर आइटम key (आवश्यक), value (आवश्यक), और secret (वैकल्पिक, boolean) से बना होता है। secret को true रखने पर वह मान प्रेषण अभिलेख में छिपा हुआ रहता है (नीचे WebhookLog देखें)। पर इस Webhook को पढ़ने पर वह मान मूल रूप में आता है। प्रतिक्रिया से केवल basicAuth.password हटता है, इसलिए यह मानकर चलें कि secret हेडर में रखा मान इस Webhook को पढ़ सकने वाली भूमिका को दिख जाता है, और उस भूमिका को सीमित रखें।

topics

topics का हर आइटम {संसाधन}.{क्रिया} प्रारूप में होता है। उदाहरण: Content.Create, Content.Publish, Media.Create।

क्रिया निम्न में से कोई एक होती है, या संसाधन की सभी क्रियाओं को दर्शाने वाला * होता है (उदाहरण: Content.*)।

filters

filters एक ऐसा सरणी है जो सदस्यता वाले topics में से वास्तव में Webhook को ट्रिगर करने वाली शर्तों को सीमित करता है। हर फ़िल्टर का स्वरूप इस प्रकार है।

{ "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }

• doc: तुलना किए जाने वाले फ़ील्ड का पथ। sys.id, sys.contentType.sys.id, sys.createdBy.sys.id, sys.updatedBy.sys.id में से एक होता है।
• op: तुलना संकारक। EQ, NE, IN, NOT_IN, REGEX, NOT_REGEX में से एक होता है।
• value: तुलना मान। EQ, NE, REGEX, NOT_REGEX को एक स्ट्रिंग दें, और IN, NOT_IN को स्ट्रिंग का सरणी दें।

कई फ़िल्टर रखने पर ट्रिगर के लिए सभी का संतुष्ट होना आवश्यक है (AND)। filters खाली रखने पर सदस्यता वाले topics की सभी घटनाएँ ट्रिगर होती हैं।

transformation

transformation url पर बाहर जाने वाले HTTP अनुरोध के स्वरूप को बदलता है (script का उपयोग करने वाले Webhook पर यह लागू नहीं होता)। निर्दिष्ट न करने पर संसाधन का पूरा पेलोड डिफ़ॉल्ट POST के रूप में ज्यों का त्यों बाहर जाता है।

बॉडी किस प्रारूप में बाहर जाती है

contentType बॉडी का सीरियलाइज़ेशन प्रारूप तय करता है। तुलना अक्षरों के बड़े-छोटे होने और ;charset=… जैसे पैरामीटरों को अनदेखा करके केवल शुरुआती हिस्से को देखती है। निर्दिष्ट न करने पर, या मान खाली होने पर, बॉडी application/json के रूप में भेजी जाती है। यदि includeBody false है या method GET है, तो बॉडी नहीं भेजी जाती, और उस स्थिति में Content-Type भी नहीं जुड़ता।

Webhook जो बॉडी भेजता है, वह सदैव एक ऑब्जेक्ट होती है। इसका कारण यह है कि body टेम्पलेट एक ऑब्जेक्ट होता है, और टेम्पलेट न रखने पर ट्रिगर हुआ पूरा संसाधन ज्यों का त्यों बाहर जाता है।

text/plain में ऑब्जेक्ट नहीं रखा जा सकता, इसलिए बॉडी को उस प्रारूप में सुधारकर भेजा जाता है जिसमें उसे रखा जा सके। हेडर वास्तविक बॉडी से भिन्न बात कभी नहीं कहता। यदि लक्ष्य को बॉडी पाठ के रूप में ही प्राप्त करनी हो, तो contentType से यह हल नहीं होता, इसलिए प्राप्त करने वाले पक्ष का अनुबंध जाँच लें।

form-urlencoded ऑब्जेक्ट को ब्रैकेट कुंजियों में और सरणी को इंडेक्स में फैलाता है।

कुंजियाँ और मान UTF-8 में परसेंट-एन्कोड होकर बाहर जाते हैं। ऊपर की तालिका कुंजी की संरचना दिखाने के लिए उन्हें डिकोड किए हुए रूप में देती है। मान में & या + होने पर भी उसे जोड़े का विभाजक या रिक्त स्थान नहीं समझा जाता, और वह ज्यों का त्यों पहुँचाया जाता है।

नेस्टिंग को ब्रैकेट कुंजियों में फैलाने की यह संकेत-पद्धति व्यापक रूप से प्रचलित परिपाटी है, प्रारूप का अपना विनिर्देश नहीं। जाँच लें कि प्राप्त करने वाला पक्ष product[sku] को नेस्टेड ऑब्जेक्ट में पुनर्स्थापित करता है या नहीं, और यदि नहीं करता, तो body टेम्पलेट को समतल कुंजियों से बनाएँ।

फ़ॉर्म के रूप में भेजने वाले transformation का एक उदाहरण यह है।

"transformation": {
  "method": "POST",
  "contentType": "application/x-www-form-urlencoded",
  "includeBody": true,
  "body": {
    "sku": "{ /payload/fields/sku/ko-KR }",
    "price": "{ /payload/fields/price/ko-KR }"
  }
}

जिस Content का sku TUMBLER-500 और price 24000 है, वह ट्रिगर करने पर बॉडी sku=TUMBLER-500&price=24000 के रूप में बाहर जाती है।

basicAuth

basicAuth url पर बाहर जाने वाले अनुरोध में HTTP Basic प्रमाणीकरण (Authorization: Basic … हेडर) जोड़ता है। script का उपयोग करने वाले Webhook पर यह लागू नहीं होता।

"basicAuth": { "username": "dailywear", "password": "<पासवर्ड>" }

बनाते समय basicAuth निर्दिष्ट करने पर username और password दोनों भेजना आवश्यक है।

पठन प्रतिक्रिया में password नहीं होता, इसलिए पूर्ण संशोधन (PUT) basicAuth को निम्न तीन तरीकों से समझता है।

पठन प्रतिक्रिया को ज्यों का त्यों संशोधित करके फिर से भेजने पर केवल username जाता है, इसलिए पासवर्ड बना रहता है। username के बिना केवल password भेजने पर अनुरोध अस्वीकृत हो जाता है।

आंशिक संशोधन (PATCH) भी इसी नियम का पालन करता है। जो संक्रिया basicAuth को नहीं छूती, वह सहेजे गए password को बनाए रखती है। password बदलने के लिए replace नहीं, बल्कि add संक्रिया का उपयोग करें ({ "op": "add", "path": "/basicAuth/password", "value": "<नया पासवर्ड>" })। लक्ष्य दस्तावेज़ में password नहीं होता, इसलिए replace अस्वीकृत हो जाता है।

प्रेषण अभिलेख (WebhookLog) में basicAuth द्वारा बनाए गए Authorization हेडर का मान छिपा हुआ रहता है।

url और script (ठीक एक)

Webhook ट्रिगर होने पर दो में से एक कार्य करता है। यदि आप url निर्दिष्ट करते हैं, तो यह उस बाहरी URL पर HTTP अनुरोध भेजता है (अनुरोध का स्वरूप transformation, headers, और basicAuth से तय होता है)। यदि आप script निर्दिष्ट करते हैं, तो यह बाहर नहीं जाता, बल्कि Space के अंदर एक Script को चलाता है।

• url: बाहरी लक्ष्य URL (http/https)। निजी नेटवर्क या लूपबैक जैसे अवरुद्ध लक्ष्य अस्वीकृत हो जाते हैं।
• script: चलाए जाने वाले Script का Refer।

दोनों में से ठीक एक को निर्दिष्ट करना आवश्यक है। दोनों निर्दिष्ट करने पर, या दोनों खाली छोड़ने पर, अनुरोध अस्वीकृत हो जाता है, और लौटने वाला कोड हर पथ के लिए अलग होता है (त्रुटियाँ देखें)।

"script": { "sys": { "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK", "type": "Refer", "targetType": "Script" } }

ट्रिगर होने पर Script प्रत्यायोजित (delegated) अनुमतियों के साथ चलता है, और प्रति-statement संसाधन अनुमतियाँ चलने के समय दोबारा जाँची नहीं जातीं। क्या अनुमत है, यह Script के रचे जाने के समय ही जाँच लिया जाता है। विस्तृत निष्पादन और अनुमति मॉडल के लिए Script के निष्पादन सिमेंटिक्स, बाधाएँ, सुरक्षा देखें।

runAs

runAs यह तय करता है कि script किस उपयोगकर्ता पहचान के रूप में चलता है। यह पहचान निष्पादन के दौरान बनाए या संशोधित किए गए किसी भी संसाधन का createdBy/updatedBy बनती है, और Script के अंदर का createdBy: ":self" फ़िल्टर भी इसी पहचान के आधार पर हल होता है। यह केवल गुणारोपण (attribution) है, अनुमति की सीमा नहीं। यह क्या कर सकता है, यह Script के रचे जाने के समय की गई अनुमति जाँच से तय होता है।

केवल url का उपयोग करने वाले Webhook में runAs को अनदेखा किया जाता है। निर्दिष्ट न करने पर यह HookOwner होता है।

WebhookLog

Webhook जब भी एक बार प्रेषण का प्रयास करता है, तब एक अभिलेख बनता है। यह केवल पठन के लिए है और इसमें बनाने, संशोधन या विलोपन के एंडपॉइंट नहीं हैं। इसका पथ /spaces/{spaceId}/webhooks/{webhookId}/logs है।

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PWhc01Exam",
    "type": "WebhookLog",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "requestId": "3trmXRM3qWnLb7Vd1yPcYs04kKrjq",
    "statusCode": 200,
    "errors": [],
    "eventType": "Create",
    "url": "https://api.dailywear.example/webhooks/products",
    "requestAt": "2026-06-18T11:35:00.100Z",
    "responseAt": "2026-06-18T11:35:00.350Z",
    "request": {
      "url": "https://api.dailywear.example/webhooks/products",
      "method": "POST",
      "headers": { "Content-Type": "application/json", "X-Source": "weegloo" },
      "body": "{\"sys\":{\"type\":\"Content\"}}"
    },
    "response": {
      "url": "https://api.dailywear.example/webhooks/products",
      "headers": { "Content-Type": "application/json" },
      "body": "{\"ok\":true}",
      "statusCode": 200
    },
    "createdBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PWhk01Examp", "type": "Refer", "targetType": "Webhook" } },
    "createdAt": "2026-06-18T11:35:00.350Z",
    "updatedBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PWhk01Examp", "type": "Refer", "targetType": "Webhook" } },
    "updatedAt": "2026-06-18T11:35:00.350Z"
  }
}

सभी मान sys के अंदर होते हैं और कोई बॉडी गुण नहीं होता। जिन कुंजियों का मान नहीं होता वे प्रतिक्रिया से हट जाती हैं।

यह अभिलेख किस Webhook का है, यह sys.createdBy बताता है। वह किसी उपयोगकर्ता का नहीं, बल्कि उस Webhook का Refer है, और sys.updatedBy भी वही Webhook है।

request और response में क्रमशः निम्न कुंजियाँ होती हैं।

• request: url (जिस लक्ष्य URL पर अनुरोध भेजा गया) · method (HTTP मेथड) · headers (भेजे गए हेडर का मैप) · body (भेजी गई बॉडी की स्ट्रिंग)।
• response: url (जिस URL से प्रतिक्रिया मिली) · headers (प्राप्त हेडर का मैप) · body (प्राप्त बॉडी की स्ट्रिंग) · statusCode (प्राप्त स्थिति कोड)।

script से Script चलाने वाले Webhook के अभिलेख का स्वरूप अलग होता है। भेजने का कोई पता न होने से url नहीं होता, और request का method "SCRIPT" पर तय रहता है। request की body में उस प्रेषण को कराने वाला payload आता है, और response की body में उस Script द्वारा लौटाया गया मान (या विफलता संदेश) आता है।

जिस हेडर का secret चालू है उसका मान, और basicAuth द्वारा बनाए गए Authorization हेडर का मान, छिपाकर सहेजे जाते हैं। वास्तविक मान अभिलेख में नहीं रहता।

लंबी बॉडी छोटी करके सहेजी जाती है। request की body के लिए 65,536 अक्षर और response की body के लिए 8,192 अक्षर का मानक है। उससे लंबी होने पर आगे और पीछे का हिस्सा रखकर बीच का भाग छोड़ दिया जाता है, और छोड़े गए अक्षरों की संख्या उसी जगह लिख दी जाती है। बॉडी JSON हो तो संरचना न टूटे इसलिए केवल लंबे स्ट्रिंग मान उसी तरीके से छोटे किए जाते हैं, इसलिए कुंजियाँ और छोटे मान ज्यों के त्यों रहते हैं।

सफलता और विफलता तय करने का मानक हर एकीकरण तरीके के लिए अलग है। URL पर भेजने वाला Webhook तब सफल होता है जब प्रतिक्रिया 2xx या 3xx हो। script से Script चलाने वाला Webhook तब सफल होता है जब statusCode 400 से छोटा हो और errors खाली हो। यही एक निर्णय नीचे दी गई संरक्षण अवधि और प्रेषण स्थिति की सफलता दर, दोनों को साथ में तय करता है।

सूची पठन request और response को हटाकर लौटाता है। इसका कारण यह है कि सूची एंडपॉइंट के select का डिफ़ॉल्ट मान -sys.response,-sys.request है। भेजे गए अनुरोध और प्राप्त प्रतिक्रिया की बॉडी तक देखनी हो, तो एकल पठन का उपयोग करें, या select स्वयं निर्दिष्ट करके उस डिफ़ॉल्ट मान को अधिलिखित करें।

सफल प्रेषण का अभिलेख 1 घंटे बाद और विफल प्रेषण का अभिलेख 3 दिन बाद मिट जाता है। समाप्ति का समय रखने वाला कोई फ़ील्ड प्रतिक्रिया में नहीं होता, और समय आने पर अभिलेख स्वयं मिट जाता है। उससे अधिक समय तक रखने योग्य मानों को प्राप्त करने वाले सर्वर पर अलग से सहेजें, या script से चलने वाले Script में Content के रूप में छोड़ें।

त्रुटियाँ

ये कोड Webhook के साथ काम करते समय मिलते हैं। सभी संसाधनों में समान रूप से मिलने वाले कोड के लिए सामान्य त्रुटियाँ देखें।

API

नीचे दिए गए सभी एंडपॉइंट का आधार URL https://cma.weegloo.com/v1 है, और Authorization हेडर में CMA को प्रमाणित करने वाला Bearer टोकन आवश्यक है। संशोधन (PUT) और आंशिक संशोधन (PATCH) के लिए आशावादी समवर्तीता नियंत्रण हेतु X-Weegloo-Version हेडर (संसाधन का वर्तमान sys.version) भी भेजना आवश्यक है।

संबंधित दस्तावेज़

• Content: वह बॉडी डेटा जिस पर Webhook ट्रिगर होता है।
• Media: वह फ़ाइल संसाधन जो Webhook को ट्रिगर कर सकता है।
• Script: script के माध्यम से चलाया जाने वाला घोषणात्मक बैकएंड एंडपॉइंट। इसमें निष्पादन और अनुमति मॉडल शामिल है।
• SpaceRole: वह भूमिका सेटिंग जो Script निष्पादन (Execute) जैसी अनुमतियाँ रखती है।