वेबहुक

वेबहुक आपको अन्य बाहरी ऐप्लिकेशन के साथ Zoho Mail को इंटीग्रेट करने देते हैं। किसी बाहरी ऐप्लिकेशन से रीयल-टाइम ईवेंट्स का उपयोग करते हुए किसी एक ऐप्लिकेशन में कोई एक्शन ट्रिगर करने के लिए एक वेबहुक का उपयोग किया जाता है। वेबहुक दो प्रकार के होते हैं - इनकमिंग वेबहुक और आउटगोइंग वेबहुक। थर्ड-पार्टी ऐप्लिकेशन से रीयल-टाइम ईवेंट्स का उपयोग करके Zoho Mail में किसी एक्शन को ट्रिगर करने के लिए इनकमिंग वेबहुक का उपयोग किया जाता है। आउटगोइंग वेबहुक द्वारा, आपके इनकमिंग ईमेल/ बनाए गए नए टास्क को कॉन्फ़िगर किया जा सकता है जिससे कि बाहरी ऐप्लिकेशन में एक्शन को ट्रिगर किया जा सके।

यह कैसे कार्य करता है?

Zoho Mail और किसी थर्ड-पार्टी ऐप्लिकेशन के बीच इंटीग्रेशन सेट करने के लिए, आपको एक ऐप्लिकेशन में इनकमिंग वेबहुक और दूसरे ऐप्लिकेशन में आउटगोइंग वेबहुक कॉन्फ़िगर करना होगा। उदाहरण के लिए, यदि आप किसी बाहरी ऐप्लिकेशन से ईवेंट्स को अपने स्ट्रीम्स समूह में पोस्ट करना चाहते हैं, तो आपको निम्न स्टेप्स का पालन करना होगा:

1. Zoho Mail में एक इनकमिंग वेबहुक कॉन्फ़िगर करें।
2. इनकमिंग वेबहुक बनाते समय जनरेट किया गया वेबहुक URL प्राप्त करें।
3. प्राप्त वेबहुक URL का उपयोग करके थर्ड-पार्टी ऐप्लिकेशन में आउटगोइंग वेबहुक कॉन्फ़िगर करें।

यदि आप ईमेल प्राप्त करते समय बाहरी ऐप्लिकेशन में कोई ईवेंट ट्रिगर करना चाहते हैं, तो आपको Zoho Mail में आउटगोइंग वेबहुक और थर्ड-पार्टी ऐप्लिकेशन में इनकमिंग वेबहुक कॉन्फ़िगर करने की आवश्यकता है।

इनकमिंग वेबहुक्स

कोई इनकमिंग वेबहुक आपको किसी थर्ड-पार्टी ऐप्लिकेशन में निर्दिष्ट ईवेंट होने पर अपनी पसंद के URL पर पोस्ट करने देता है। आप बाहरी ऐप्लिकेशन से प्राप्त जानकारी का उपयोग करके अपने स्ट्रीम समूह में संदेश, नोट या टास्क पोस्ट करने के लिए इनकमिंग वेबहुक को कॉन्फ़िगर कर सकते हैं।

इनकमिंग वेबहुक कॉन्फ़िगर करना

1. Zoho Mail में लॉग इन करें
2. सेटिंग्स > इंटीग्रेशन] > डेवलपर स्पेस पर नेविगेट करें
3. बाएँ मेनू में कॉन्फ़िगर करें सेक्शन के तहत इनकमिंग वेबहुक्स को चुनें।
4. नया कॉन्फ़िगरेशन जोड़ें पर क्लिक करें
   
5. पोस्ट फ़ॉर्मेट को चुनें
   • ​मेल - वेबहुक अपडेट को आपके इनबॉक्स में ईमेल के रूप में भेजा जाएगा।
   • पोस्ट/ नोट्स/ टास्क - वेबहुक अपडेट पसंदीदा स्ट्रीम समूह में पोस्ट/नोट/टास्क के रूप में पोस्ट किया जाएगा
6. यदि आपने पिछले स्टेप्स में मेल चुना है, तो इस स्टेप को छोड़ें। यदि आपने पोस्ट/ नोट्स/ टास्क चुना है, तो कॉन्फ़िगरेशन पेज पर निम्न विवरण प्रदान करें:
   • कस्टम उपयोगकर्ता नाम - इस नाम का इस्तेमाल स्ट्रीम में पोस्ट करने के लिए किया जाएगा
   • समूह - वह समूह जहाँ अपडेट पोस्ट किए जाएँगे
7. फिर, यदि आप पोस्ट अनुरोध में डेटा को अपनी आवश्यकताओं के अनुसार वेबहुक फ़ॉर्मेट के अनुरूप संशोधित करना चाहते हैं, तो कस्टम फ़ंक्शन के तहत लिखें फ़ंक्शन पर क्लिक करें। आपके द्वारा कस्टम फ़ंक्शन बनाने के बाद, कस्टम फ़ंक्शन चुनें पर क्लिक करें।
   नोट:
   आप DRE कनेक्टर्स का उपयोग करके अपनी पसंद के किसी भी थर्ड-पार्टी ऐप्लिकेशन के साथ कनेक्शन भी स्थापित कर सकते हैं।
8. URL जनरेट करें पर क्लिक करें और बनाए गए URL को कॉपी करें।
   ​

जनरेट किया गया URL आपकी पसंद के थर्ड-पार्टी ऐप्लिकेशन में आउटगोइंग वेबहुक कॉन्फ़िगर करने के दौरान उपयोग किया जाता है।

याद रखने योग्य पॉइंट्स

• यदि आप चाहते हैं कि स्ट्रीम पोस्ट में @mention शामिल हो, तो संदेश के मुख्य भाग में निम्न शामिल करें:
  • समूह के सदस्य को @mention करने के लिए, संदेश में @mailID शामिल करें। उदाहरण: रेबेका को @mention करने के लिए, @rebecca@zylker.com
  • किसी समूह को @mention करने के लिए संदेश में @group शामिल करें। वेबहुक के लिए कॉन्फ़िगर किया गया समूह स्वचालित रूप से टैग हो जाएगा।
• अनधिकृत व्यक्तियों के समक्ष वेबहुक URL को डिस्क्लोज़ नहीं किया जाना चाहिए। यदि डिस्क्लोज़ होता है, तो वे आपके स्ट्रीम समूह में अपडेट पोस्ट कर सकेंगे।
• यदि आप वेबहुक URL फिर से जनरेट करते हैं, तो आपको हर जगह पुराने URL को नए URL से बदलने की आवश्यकता होगी।

आउटगोइंग वेबहुक्स

एक आउटगोइंग वेबहुक्स आपको थर्ड-पार्टी ऐप्लिकेशन में ईवेंट्स ट्रिगर करने के लिए अपने ईमेल/ टास्कों को कॉन्फ़िगर करने देता है। आप बाहरी ऐप्लिकेशन पर प्राप्त होने वाले ईमेल/टास्कों के विवरण पोस्ट कर सकते हैं। कॉन्फ़िगरेशन में फ़िल्टर्स विकल्प आपको उन ईमेल/टास्कों का चयन करने देता है जिन्हें आप चाहते हैं कि वे ईवेंट के लिए ट्रिगर के रूप में कार्य करें।

आउटगोइंग वेबहुक​ कॉन्फ़िगर करना

1. Zoho Mail में लॉग इन करें
2. सेटिंग्स > इंटीग्रेशन] > डेवलपर स्पेस पर नेविगेट करें
3. बाएँ मेनू में कॉन्फ़िगर करें सेक्शन के तहत आउटगोइंग वेबहुक्स को चुनें।
4. नया कॉन्फ़िगरेशन जोड़ें पर क्लिक करें
   
5. कस्टम उपयोगकर्ता नाम और वेबहुक URL भरने के बाद, आपको उस एंटिटी का चयन करना होगा जिसे आप कॉन्फ़िगर करना चाहते हैं जैसे कि मेल या टास्क।
   • कस्टम उपयोगकर्ता नाम - वेबहुक कॉन्फ़िगरेशन को दिया गया नाम
   • वेबहुक URL - थर्ड-पार्टी ऐप्लिकेशन में इनकमिंग वेबहुक कॉन्फ़िगरेशन से प्राप्त URL। या तो मेल या टास्क से ट्रिगर किए गए अपडेट इस URL पर पोस्ट किए जाएँगे।
6. यदि आप मेल चुनते हैं, तो आप अगले स्टेप को छोड़ सकते हैं। आपको एक मेल स्थिति प्रकार और एक शर्त चुननी चाहिए जिसके लिए आपको वेबहुक को ट्रिगर करने की आवश्यकता है।
   
   • शर्त का प्रकार - चुनें कि आप फ़िल्टर एक्शन कैसे चलाना चाहते हैं। फ़िल्टर्स के बारे में अधिक जानने के लिए, यहां क्लिक करें
   • शर्तें - मेल का शर्त प्रकार चुनने के बाद, इच्छित शर्त प्रदान करें। उदाहरण के लिए, शर्त प्रेषक में rebecca@zylker.com हो सकती है। मेल की शर्तों के बारे में अधिक जानने के लिए, यहां क्लिक करें।
   • टैग किए गए ईमेल- यदि आप टैग किए गए ईमेल का चयन करते हैं, तो आपको टैग चुनें ड्रॉप-डाउन से टैग्स चुनने होंगे। आप अधिकतम 3 टैग्स चुन सकते हैं।
     • टैग किए गए ईमेल शर्त केवल विशिष्ट टैग्स (न्यूज़लेटर, मार्केटिंग, आदि) के तहत आने वाले ईमेल का ही चयन करती है। यदि आप चाहते हैं कि विशिष्ट टैग्स से मार्क किए गए ईमेल वेबहुक को ट्रिगर करें, तो यह विकल्प चुनें। आपके द्वारा टैग्स का चयन करने के बाद, जब भी कोई इनकमिंग ईमेल चयनित टैग्स में से किसी के भी साथ मार्क किया जाता है या जब आप किसी ईमेल को बाद में उन चयनित टैग्स में से एक या अधिक के साथ मार्क करते हैं, तो वेबहुक ट्रिगर हो जाएगा। हालाँकि, यदि आप टैग किए गए ईमेल चुनते हैं, तो आप अतिरिक्त शर्तें निर्दिष्ट नहीं कर सकते हैं।
   • केवल Meta - यदि आप इस विकल्प का चयन करते हैं, तो थर्ड-पार्टी ऐप्लिकेशन में ईमेल के केवल विषय, प्रेषक. प्राप्तकर्ता और समय विवरण ही पोस्ट किए जाएँगे।
     
7. यदि आप टास्कों का चयन करते हैं, तो आपको वह टास्क गतिविधि का चयन करना चाहिए जिसके लिए आपको वेबहुक ट्रिगर करने और आपको सूचित करने की आवश्यकता है। जब भी आपको असाइन किए गए टास्क में चयनित गतिविधि होती है, तो वेबहुक ट्रिगर हो जाएगा।
   • टास्क गतिविधियों को चुनें - वे गतिविधियाँ चुनें जिनके लिए आप सूचना प्राप्त करना चाहते हैं। चयन करने के बाद, आपको असाइन किए गए टास्कों में केवल चयनित गतिविधियाँ थर्ड-पार्टी ऐप्लिकेशन में ईवेंट्स को ट्रिगर करेंगी।
   • समूह(समूहों) को चुनें- टास्कों के लिए, आप विशेष स्ट्रीम समूहों का चयन कर सकते हैं और वेबहुक तभी ट्रिगर होगा जब आपके द्वारा चुनी गई टास्क गतिविधियां उन चयनित समूहों में होती हैं। आप अधिकतम 3 समूह ही चुन सकते हैं।
   • केवल Meta - यदि आप इस विकल्प का चयन करते हैं, तो थर्ड-पार्टी ऐप्लिकेशन में केवल टास्क विवरण का Meta डेटा ही पोस्ट किया जाएगा। टास्क विवरण के पूर्ण डेटा और Meta डेटा के बीच का अंतर नीचे दी गई तालिका में दिया गया है।

     पूर्ण डेटा	केवल Meta डेटा	विवरण
     असाइनी	असाइनी	असाइनी की उपयोगकर्ता ID (Zuid)
     असाइनी का नाम	असाइनी का नाम	असाइनी का उपनाम
     displayName	displayName	असाइनी का पूरा नाम
     शीर्षक	शीर्षक	टास्क का टाइटल
     सारांश		टास्क का वर्णन
     entityId	entityId	टास्क की ID
     entityType	entityType	एंटिटी का प्रतिनिधित्व करता है। उदाहरण के लिए, 3 इंगित करता है कि यह एक टास्क एंटिटी है।
     categoryId		केटेगरी की ID
     categoryName		केटेगरी का नाम
     dueDate	dueDate	न्यूमेरिक मान में नियत दिनांक मान।
     प्राथमिकता		नंबर में उल्लेखित टास्क की प्राथमिकता
     parentTaskId		पेरेंट की टास्क Id (यदि ट्रिगर किया गया टास्क एक सब-टास्क है)
     nameSpaceId	nameSpaceId	समूह की ID
     groupName	groupName	समूह का नाम
     triggerZuid	triggerZuid	एक्शन को ट्रिगर करने वाले अकाउंट की उपयोगकर्ता Id
     स्टेटस	स्टेटस	नंबर में वर्णित स्टेटस
     statusName		टास्क का स्टेटस नाम
     एक्शन	एक्शन	ट्रिगर किए गए टास्क एक्शन का नाम

8. यदि आप अपनी आवश्यकताओं के अनुसार वेबहुक फ़ॉर्मेट के अनुसार पोस्ट अनुरोध में डेटा को संशोधित करना चाहते हैं, तो कस्टम फ़ंक्शन के तहत फ़ंक्शन लिखें पर क्लिक करें। कस्टम फ़ंक्शन बनाने के बाद, फ़ंक्शन का चयन करने के लिए कस्टम फ़ंक्शन को चुनें पर क्लिक करें।
9. सेव करें पर क्लिक करें।

वेबहुक रिसपॉन्स नमूना:

{
"सारांश": "नमस्ते रेबेका, मैंने शुक्रवार को अपनी प्रोडक्ट पिच मीटिंग के लिए स्लाइड डेक शेयर किया है। कृपया इस पर एक नज़र डालें और यदि आपके पास कोई सुझाव है तो मुझे बताएँ। धन्यवाद, पाउला",
"sentDateInGMT": 1560866021000,
"विषय": "मार्केटिंग - प्रोडक्ट पिच",
"messageId": 1560840837125110000,
"toAddress": ""रेबेका A"<rebecca@zylker.com>",
"folderId": 3881227000000013000,
"zuid": 647772765,
"ccAddress": "",
"आकार": 55503,
"प्रेषक": "पाउला",
"receivedTime": 1560840837126,
"fromAddress": "paula@zylker.com",
"html": "<meta /><div><div style="font-family:"Trebuchet ms", Arial, Helvetica, sans-serif;font-size:12pt;"><div>नमस्ते, रेबेका,<br /></div><div><br /></div><div>मैंने शुक्रवार को हमारी प्रोडक्ट पिच मीटिंग के लिए स्लाइड डेक शेयर किया है। कृपया एक नज़र डालें और मुझे बताएं कि क्या आपके पास कोई सुझाव हैं।<br /></div><div id=""><div><img src="/zm/ImageDisplay?f=1.png&mode=inline&cid=0.28869215260.3894179596053002321.16b695cdb49__inline__img__src&" width="145" height="145" style="float:left;" /><br /></div><div><br /></div><div><br /></div><div>आभार,<br /></div><div>Paula<br /><br /></div></div><br /><br /><div style="clear:both;"></div></div><br /></div>",
"IntegIdList": "34000000580271,"
}

वेबहुक्स को सुरक्षित करना

आपको अपने वेबहुक को सुरक्षित रखने की सलाह दी जाती है क्योंकि यह निर्धारित करने में आपकी मदद करता है कि क्या अनुरोध वास्तव में Zoho Mail से उत्पन्न हुए हैं। आप वेबहुक्स सत्यापित कर सकें, इसके लिए Zoho Mail उसके सभी वेबहुक अनुरोधों में एक हस्ताक्षर जोड़ता है। यह आपके वेबहुक में सुरक्षा का एक अतिरिक्त लेयर जोड़ता है।

वेबहुक अनुरोधों को सत्यापित करना

सत्यापन करने के लिए हर वेबहुक अनुरोध में एक हस्ताक्षर होता है। संदेश पर हस्ताक्षर करने के लिए जिस की का उपयोग किया जाता है वह x-हुक-सीक्रेट है। यह रहस्य केवल वेबहुक के पहले अनुरोध के हेडर से ही प्राप्त होता है। x-हुक-हस्ताक्षर सभी अनुरोधों के HTTP हेडर में पाया जाता है। हेडर HMAC SHA256 हैश का बेस 64 डाइजेस्ट है। हैश की गई सामग्री पूर्ण अनुरोध निकाय का बाइनरी प्रतिनिधित्व होना चाहिए।

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

किसी अनुरोध की वैधता की जाँच करने के लिए नमूना कोड नीचे दिया गया है:

JAVA:

javax.crypto.Mac इम्पोर्ट करें;
इम्पोर्ट करें javax.crypto.spec.SecretKeySpec;
इम्पोर्ट करें javax.servlet.http.HttpServletRequest;

//वेबहुक अनुरोध को सत्यापित करने की विधि
boolean verifyWebhookRequest(String secret, String payload, HttpServletRequest request) अपवाद देता है
{
Mac mac = Mac.getInstance("HmacSHA2256");
SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
mac.init(secretKey);
String signature = Base64.encodeBase64String(mac.doFinal(payload.getBytes()));
return signature.equals(request.getHeader("X-Hook-Signature"));
}

जावा स्क्रिप्ट:

function VerifyWebhookRequest(request, secret)
{
//URL पर वेबहुक को रजिस्टर करने के दौरान x-हुक-सीक्रेट है
var crypto = require('crypto');
var headerHash = request.headers['x-hook-signature'];
var createdHash = crypto.createHmac('sha256' , secret).update(request.body).digest('base64');
return headerHash = = = createdHash;
}