Antimatter

वेबहुक

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

वेबहुक प्रबंधन कहाँ करें

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

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

A channel with messages from a CI bot and from GitHub, shown as cards with fields, pipeline stages and a button
कार्ड के रूप में आरेखित इंटीग्रेशन सन्देश: फ़ील्ड, पाइपलाइन चरण और एक क्रिया बटन।

इनकमिंग वेबहुक बनाएँ

  1. इंटीग्रेशन में, इनकमिंग वेबहुक चुनें, फिर इनकमिंग वेबहुक जोड़ें।
  2. एक शीर्षक और एक विवरण भरें: ये केवल इंटीग्रेशन पेज पर दिखते हैं।
  3. वह चैनल चुनें जिसमें सन्देश डिफ़ॉल्ट रूप से जाएँ। निजी चैनल के लिए, आपको उसका सदस्य होना चाहिए।
  4. यदि प्रेषकों को अन्यत्र पोस्ट करने की अनुमति नहीं होनी चाहिए, तो इस चैनल पर लॉक करें पर टिक लगाएँ।
  5. वैकल्पिक रूप से, उसके सन्देशों के लिए यूज़रनेम और प्रोफ़ाइल चित्र URL सेट करें (देखें नाम और आइकन)।
  6. सहेजें चुनें। दिखाई देने वाला URL कॉपी करें: https://chat.example.com/hooks/<key>।
URL एकमात्र सिक्रेट है: जो भी इसे रखता है, वह चैनल में पोस्ट कर सकता है। इसे सार्वजनिक रिपॉज़िटरी से बाहर रखें, और यदि यह लीक हो जाए, तो वेबहुक हटा दें।

API के साथ: POST /api/v4/hooks/incoming के साथ {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; प्रतिसाद का id कुंजी है। कमांड लाइन से: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI"।

इनकमिंग वेबहुक पर सन्देश भेजें

curl -X POST https://chat.example.com/hooks/xgh5ycrx1jf7mbs9w8z4c8e7ho \
  -H 'Content-Type: application/json' \
  -d '{"text": "Deploy of **api 2.4.0** finished :white_check_mark:"}'

सर्वर 200 के साथ ok बॉडी का जवाब देता है। यह application/x-www-form-urlencoded भी स्वीकार करता है, जिसमें JSON payload फ़ील्ड में होता है, जैसे Slack के वेबहुक करते हैं, इसलिए Slack के लिए बनाए गए टूल्स आमतौर पर बिना बदलाव के काम करते हैं।

फील्डअर्थ
textMarkdown में संदेश। attachments न होने पर यह अनिवार्य है। यदि टेक्स्ट सर्वर के संदेश सीमा से लंबा है, तो उसे कई संदेशों में बांटा जाता है।
channelवेबहुक की कम्युनिटी का कोई अन्य चैनल, नाम से (ops-alerts या #ops-alerts), या वेबहुक के मालिक से डायरेक्ट मैसेज के लिए @username। यदि वेबहुक अपने चैनल तक सीमित है, तो यह अस्वीकार कर दिया जाता है। पुराना नाम town-square अब general कहलाते कम्युनिटी के डिफ़ॉल्ट चैनल तक अभी भी पहुँचता है।
username, icon_url, icon_emojiदिखाने के लिए नाम और चित्र, यदि सर्वर ओवरराइड की अनुमति देता है।
attachmentsसंदेश के अटैचमेंट, जो कार्ड के रूप में (नीचे) दिखाए जाते हैं।
propsसंदेश पर सहेजे गए अतिरिक्त गुण, जो ऐप्स पढ़ते हैं।
typeकस्टम पोस्ट प्रकार, जैसे custom_poll, किसी ऐप के लिए जो इसे दिखाता है। system_ से शुरू होने वाले प्रकार अस्वीकार कर दिए जाते हैं।
root_idकिसी थ्रेड के पहले संदेश की ID, ताकि उसी थ्रेड में उत्तर दिया जा सके।
priorityसंदेश प्राथमिकता, उदाहरण के लिए {"priority": "urgent"}।
silenttrue संदेश को पुश सूचनओं के बिना भेजता है।

वेबहुक द्वारा पोस्ट किया गया हर संदेश उसके नाम के बगल में बॉट टैग लेता है, भले ही वह उसके निर्माता के नाम से दिखाई दे, ताकि लोग इसे किसी असली व्यक्ति के संदेश से अलग पहचान सकें। वेबहुक संदेश कभी आउटगोइंग वेबहुक को ट्रिगर नहीं करते।

नाम और आइकन

वेबहुक उस व्यक्ति के रूप में पोस्ट करता है जिसे उसने बनाया, जब तक कि सर्वर ओवरराइड की अनुमति न दे। सिस्टम कंसोल › इंटीग्रेशन › इंटीग्रेशन प्रबंधन में दो सेटिंज हैं, जो दोनों डिफ़ॉल्ट रूप से बंद हैं, और जो इसे बदलती हैं:

  • इंटीग्रेशन को यूज़रनेम ओवरराइड करने की अनुमति दें (ServiceSettings.EnablePostUsernameOverride): वेबहुक का यूज़रनेम या अनुरोध का username दिखाया जाता है; यदि न तो वेबहुक का नाम है और न ही अनुरोध में, तो नाम webhook होता है।
  • इंटीग्रेशन को प्रोफ़ाइल चित्र आइकन ओवरराइड करने की अनुमति दें (ServiceSettings.EnablePostIconOverride): वेबहुक का प्रोफ़ाइल चित्र, या अनुरोध का icon_url या icon_emoji, दिखाया जाता है।

अनुरोध में दिया गया मान वेबहुक पर सहेजे गए मान पर प्राथमिकता रखता है।

अटैचमेंट

अटैचमेंट टेक्स्ट के नीचे संरचित सामग्री जोड़ते हैं। वे Slack के संदेश अटैचमेंट फ़ॉर्मेट का पालन करते हैं:

{
  "text": "Build failed on `main`",
  "attachments": [{
    "fallback": "main #1902 failed",
    "color": "#d24b4e",
    "author_name": "GitHub Actions",
    "author_icon": "https://chat.example.com/static/ci.png",
    "title": "main #1902 failed",
    "title_link": "https://ci.example.com/runs/1902",
    "text": "Commit `0f4d8e2` by Jonas Weber",
    "fields": [
      {"title": "Branch", "value": "zephyr-3.7", "short": true},
      {"title": "Duration", "value": "3m 40s", "short": true}
    ],
    "footer": "Lumen CI",
    "ts": 1760000000
  }]
}
फील्डअर्थ
fallbackसामान्य टेक्स्ट, उन स्थानों के लिए जो कार्ड नहीं दिखा सकते, जैसे सूचनाएँ।
colorरंगी पट्टी: एक हेक्स रंग, या good, warning, danger।
pretextकार्ड के ऊपर टेक्स्ट।
author_name, author_link, author_iconएक छोटा हेडर लाइन।
title, title_linkकार्ड का शीर्षक, यदि चाहें तो एक लिंक।
textकार्ड का मुख्य भाग, Markdown में।
fields{"title", "value", "short"} की एक सूची; short फ़ील्ड एक-साथ (side by side) रखी जाती हैं।
image_url, thumb_urlनीचे एक बड़ी छवि, या किनारे पर एक छोटी छवि।
footer, footer_icon, tsएक फुटर लाइन और समय (Unix seconds में)।
actionsबटन और मेन्यू: Interactive messages देखें।

कार्ड: stages और charts

Antimatter attachments में दो फ़ील्ड जोड़ता है, जो डिफ़ॉल्ट इंटरफ़ेस द्वारा प्रदर्शित की जाती हैं:

  • stages: एक pipeline के चरण, pills के रूप में, अधिकतम 20। प्रत्येक {"name", "status"} होता है, जहाँ status passed, failed, running, pending, skipped या canceled हो सकता है।
  • chart: हालिया मानों का एक छोटा लाइन चार्ट, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}। थ्रेशहोल्ड एक डैश्ड लाइन के रूप में खींचा गया है, जो अलर्ट की सीमा दर्शाता है।
{
  "attachments": [{
    "color": "danger",
    "title": "main #1902 failed",
    "stages": [
      {"name": "build", "status": "failed"},
      {"name": "unit", "status": "skipped"},
      {"name": "publish", "status": "skipped"}
    ]
  }, {
    "color": "warning",
    "title": "API latency above 400 ms",
    "chart": {"values": [210, 230, 260, 390, 450, 470], "threshold": 400, "label": "p95 latency, ms"}
  }]
}

क्लासिक इंटरफ़ेस और अन्य clients इन दो फ़ील्डों को नज़रअंदाज़ कर देते हैं, इसलिए मूल बातें text या fields में भी रखें।

आउटगोइंग वेबहुक बनाएँ

एक आउटगोइंग वेबहुक किसी community के सार्वजनिक चैनलों पर नज़र रखता है। यह आपके URL पर एक संदेश भेजता है, या तो तब जब संदेश का पहला शब्द इसके ट्रिगर शब्दों में से किसी एक से मेल खाता है, या तब जब कोई व्यक्ति संदेश के मेन्यू में इसे चुनता है (एक message action)।

  1. इंटीग्रेशन में, आउटगोइंग वेबहुक चुनें, फिर आउटगोइंग वेबहुक जोड़ें।
  2. श्रीर्षक और विवरण भरें।
  3. request का कंटेंट टाइप चुनें: application/x-www-form-urlencoded या application/json।
  4. एक चैनल चुनें, ट्रिगर शबद (एक प्रति लाइन) दर्ज करें, या दोनों। यदि चैनल है और ट्रिगर शब्द नहीं, तो उस चैनल का हर संदेश भेजा जाता है। यदि दोनों हैं, तो संदेश दोनों से मेल खाना चाहिए।
  5. ट्रिगर कब करें के तहत, पहल शबद ट्रिगर शबद से पूरि तरह मेल खात ह, पहल शबद ट्रिगर शबद से शुरू होत ह, या संदेश के मेन्यू से चुनें। संदेश के मेन्यू से चुनने पर, ट्रिगर शब्द गायब हो जाते हैं, चैनल वैकल्पिक हो जाता है (यदि न चुना जाए, तो action community के हर public channel में उपलब्ध होगी), और श्रीर्षक आवश्यक है: यह मेन्यू में action का नाम है।
  6. Callback URLs (एक प्रति लाइन) दर्ज करें। प्रत्येक URL को हर matching message मिलता है।
  7. वैकल्पिक रूप से, उत्तरों के लिए उपयोग किए जाने वाले यूज़रनेम और प्रोफ़ाइल चित्र सेट करें। संदेश मेनू से किसी एक्शन के लिए, Icon फ़ील्ड प्रोफ़ाइल चित्र की जगह लेती है: एक .png या .jpg इमेज का URL या, Antimatter के डिफ़ॉल्ट इंटरफ़ेस में, एक अपलोड की गई इमेज। मेनू इसे ग्रे रंग में दिखाता है; यदि कोई नहीं है, तो एक्शन को एक न्यूट्रल आइकन मिलता है।
  8. सहेजें चुनें और दिखाई देने वाले टोकन की कॉपी करें। आपका सर्विस इसे इसकी जाँच के लिए उपयोग करता है कि अनुरोध आपके सर्वर से आ रहे हैं।

API के साथ: POST /api/v4/hooks/outgoing के साथ {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 एक सटीक मेल के लिए, 1 "शुरुआत में" के लिए, 2 "संदेश मेनू से" के लिए)। trigger_when 2 वाला वेबहुक कोई ट्रिगर वर्ड नहीं लेता और display_name की आवश्यकता होती है। इसका आइकन POST /api/v4/hooks/outgoing/{hook_id}/icon के साथ अपलोड करें (मल्टीपार्ट, फ़ील्ड image: PNG, JPEG या GIF, 128 px PNG के रूप में स्टोर किया जाता है); इसका icon_url तब GET /api/v4/hooks/outgoing/{hook_id}/icon की ओर इशारा करता है।

यदि आपका सर्विस एक निजी नेटवर्क पर है, तो एक सिस्टम एडमिन को अविश्वसनीय आंतरिक कनेक्शन की अनुमति दें में इसका पता अनुमत करना होगा (ServiceSettings.AllowedUntrustedInternalConnections)। अन्यथा, सर्वर निजी पताओं को कॉल नहीं करता।

आउटगोइंग अनुरोध

Antimatter इन फ़ील्ड्स के साथ एक POST भेजता है, JSON या फ़ॉर्म-एनकोडेड, कंटेंट टाइप के अनुसार:

{
  "token": "6kd1ofo5ojr5zgu5ipfipybgnc",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "channel_id": "…",
  "channel_name": "ops-alerts",
  "timestamp": 1760010000000,
  "user_id": "…",
  "user_name": "priya",
  "post_id": "…",
  "text": "deploy api 2.4.0",
  "trigger_word": "deploy",
  "file_ids": ""
}

कुछ भी करने से पहले token की तुलना वेबहुक के टोकन से करें। फ़ॉर्म-एनकोडेड संस्करण में, timestamp मिलीसेकंड के बजाय सेकंड में होता है। सर्वर आपके उत्तर के इंतज़ार इंटीग्रेशन अनुरोध टाइमआउट की अनुमत के अनुसार करता है (डिफ़ॉल्ट रूप से 30 सेकंड, ServiceSettings.OutgoingIntegrationRequestsTimeout)।

आउटगोइंग वेबहुक का उत्तर

उत्तर पोस्ट करने के लिए, JSON के साथ उत्तर दें। कुछ भी पोस्ट न करने के लिए, खाली बॉडी के साथ उत्तर दें।

{
  "text": "Deploying **api 2.4.0** to staging…",
  "response_type": "comment",
  "username": "deploy-bot",
  "icon_url": "https://chat.example.com/static/deploy.png"
}
  • text और attachments: उत्तर। यदि दोनों में से कोई नहीं है, तो कुछ भी पोस्ट नहीं होता।
  • response_type: comment ट्रिगरिंग संदेश के थ्रेड में उत्तर पोस्ट करता है; अन्यथा यह चैनल में जाता है।
  • username, icon_url: तब दिखाया जाता है जब सर्वर ओवरराइड्स की अनुमति देता है; अन्यथा वेबहुक के अपने मान उपयोग किए जाते हैं।
  • props, type, priority: इनकमिंग वेबहूक्स के लिए जैसा।

उत्तर वेबहुक के निर्माता के नाम से पोस्ट होता है, यदि कोई ओवरराइड किया गया नाम हो तो उसी के नाम से। यदि जवाब एक संक्षिप्त उत्तर से लंबा है, तो तुरंत जवाब दें और बाद में इनकमिंग वेबहुक या API के माध्यम से पोस्ट करें।

मैसेज एक्शन

एक संदेश कार्रव (message action) एक आउटगोइंग वेबहुक है जिसमें ट्रिगर कब करें को From the message menu पर सेट किया गया है। यह कभी भी पोस्ट किए गए संदेशों पर फायर नहीं होता। इसके बजाय, लोग किसी संदेश के मेन्यू में इसे देखते हैं: संदेश कार्रवाई (⋯) › अधिक कार्रवाएं, इंटीग्रेशन हेडिंग के नीचे, इसके आइकन के साथ। क्लासिक इंटरफेस संदेश कार्रवों को नहीं दिखाता। इसे चुनने पर उस एक संदेश को कॉलबैक URL भेजा जाता है, और एक छोटी सूचना कार्रव के नाम के साथ Sent to दिखाती है, या आपका ephemeral_text दिखाती है।

  • जहाँ यह दिखाई देता है: वेबहुक के चैनल में, या, यदि कोई चैनल नहीं है, तो उस कम्युनिटी के हर सार्वजनिक चैनल में। केवल सार्वजनिक चैनलों में ही संदेश कार्रवें होती हैं।
  • अतिथि केवल उन कार्रवों तक पहुंच पाते हैं जो उनके उस चैनल से जुड़ी हैं जिसमें वे हैं, कम्युनिटी-व्यापी कार्रवों तक नहीं।
  • अरकाइव किए गए और केवल-पठनीय चैनल: संदेश अभी भी भेजा जा सकता है। चैनल को अरकाइव करने पर उससे जुड़े वेबहुक हटा दिए जाते हैं, इसलिए एक अरकाइव किए गए चैनल में केवल कम्युनिटी-व्यापी कार्रवें बनी रहती हैं। यदि कोई व्यक्ति वहाँ उत्तर पोस्ट नहीं कर पाता, तो वह उत्तर केवल उसे ही दिखाया जाता है।
  • रेट लिमिट: हर व्यक्ति प्रति मिनट 10 संदेश कार्रवें चला सकता है, 5 की बर्स्ट के बाद। इससे ऊपर, सर्वर 429 का उत्तर देता है।
  • निजी नेटवर्क: अन्य आउटगोइंग वेबहूक की तरह, आंतरिक पता (internal addresses) की अनुमति अविश्वसनीय आंतरिक कनेक्शन की अनुमति दें में दी जानी चाहिए।

अनुरोध

पेयलोड (payload) JSON या फॉर्म-एनकोडेड के रूप में भेजा जाता है, जैसा कि वेबहुक का कंटेंट टाइप बताता है:

{
  "token": "6kd1ofo5ojr5zgu5ipfipybgnc",
  "trigger": "message_action",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "channel_id": "…",
  "channel_name": "ops-alerts",
  "timestamp": 1760010000000,
  "user_id": "…",
  "user_name": "priya",
  "post_id": "…",
  "post_root_id": "",
  "post_create_at": 1760009000000,
  "post_user_id": "…",
  "post_user_name": "jonas",
  "permalink": "https://chat.example.com/lumen-labs/pl/…",
  "text": "The staging database is full again",
  "files": [{"id": "…", "name": "df.txt", "link": "https://chat.example.com/api/v4/files/…"}],
  "priority": "",
  "requested_ack": false,
  "burn_on_read": false
}
  • user_id और user_name उस व्यक्ति के हैं जिसने कार्रव चुनी; post_user_id और post_user_name संदेश के लेखक के हैं।
  • केवल वह संदेश भेजा जाता है, उसके थ्रेड का बाकी हिस्सा कभी नहीं।
  • files में संदेश की फाइलें तब ही सूचीबद्ध होती हैं जब कार्रव चुनने वाले व्यक्ति को उन्हें डाउनलोड करने की अनुमति हो। link डाउनलोड करने के लिए एक सेशन या टोकन की आवश्यकता होती है, जैसे API की किसी भी फाइल के लिए।
  • बर्न-ऑन-रीड (burn-on-read) संदेश अपने टेक्स्ट और फाइलों के बिना भेजा जाता है, burn_on_read को true पर सेट किया जाता है।
  • फॉर्म-एनकोडेड में, फाइलें दोहराई गई file_id, file_name और file_link फील्ड के रूप में आती हैं, उसी क्रम में।

उत्तर

किसी आउटगोइंग वेबहुक के जवाब में जैसा कि (देखें आउटगोइंग वेबहुक का उत्तर): text या attachments चैनल में एक उत्तर पोस्ट करता है, और "response_type": "comment" इसे संदेश के थ्रेड में पोस्ट करता है। आप ephemeral_text (300 अक्षरों तक) के साथ भी उत्तर दे सकते हैं: यह केवल उस व्यक्ति को दिखाया जाता है जिसने एक्शन चुना, सूचना में। एक खाली बॉडी कुछ भी पोस्ट नहीं करता।

{"ephemeral_text": "Ticket OPS-412 created"}

API के साथ

  • GET /api/v4/channels/{channel_id}/message_actions: वे एक्शन जो आप एक चैनल में चुन सकते हैं, id, display_name, description और icon_url के साथ। न तो टोकन और न कॉलबैक URL लौटाए जाते हैं।
  • POST /api/v4/posts/{post_id}/message_actions/{hook_id}: एक ऐसे संदेश पर एक्शन चलाता है जिसे आप पढ़ सकते हैं। यह {"ephemeral_text"} के रूप में उत्तर देता है।

जब वेबहुक काम नहीं करता

  • हुक URL से 501: सर्वर पर इनकमिंग वेबहुक बंद हैं।
  • 400 "Failed to decode the payload…": JSON अमान्य है, या फ़ॉर्म फ़ील्ड का नाम payload नहीं है। "No text specified." का अर्थ है कि अनुरोध में न text है और न attachments।
  • 403: वेबहुक किसी अन्य चैनल से बंधा हुआ है, या इसका मालिक अब चैनल नहीं पढ़ सकता।
  • आउटगोइंग वेबहुक कभी भी ट्रिगर नहीं होता: चैनल निज है, ट्रिगर पहला शब्द नहीं है, संदेश किसी वेबहुक से आया है, या वेबहुक को From the message menu से ट्रिगर होने के लिए सेट किया गया है।
  • एक संदेश एक्शन मेनू में नहीं है: चैनल निज है, एक्शन किसी अन्य चैनल से बंधा हुआ है, व्यक्ति एक अतिथि है और एक्शन का कोई चैनल नहीं है, या आउटगोइंग वेबहुक बंद हैं।
  • संदेश एक्शन चलाते समय 404: एक्शन मौजूद नहीं है, या वह उस व्यक्ति के लिए उस संदेश के चैनल को कवर नहीं करता। 429: व्यक्ति ने एक मिनट में 10 से अधिक एक्शन चलाए। 502: कोई भी कॉलबैक URL तक पहुंच नहीं पाया (कारण लॉग में है)।
  • लॉग: Webhook Debugging सक्षम करें चालू (LogSettings.EnableWebhookDebugging) और लॉग लेवल DEBUG पर होने पर, सर्वर असफल इनकमिंग अनुरोधों के पेयलोड्स को लॉग करता है। असफल आउटगोइंग कॉल्स को Outgoing Webhook POST failed के रूप में लॉग किया जाता है।