ویب ہکس

ایک داخلہ ویب ہک کسی دوسرے سسٹم کو ایک چینل میں JSON بھیج کر پیغام پوسٹ کرنے کی اجازت دیتا ہے۔ ایک خارجہ ویب ہک اس کا برعکس کرتا ہے: یہ آپ کے URL کو پیغامات بھیجتا ہے، جو ٹریگر ورڈ سے شروع ہوں یا جو لوگ پیغام کے مینیو میں اسے منتخب کریں، اور پھر آپ کے جواب کو پوسٹ کرتا ہے۔

ویب ہکس کا انتظام کہاں کریں

اوپر دائیں جانب اپنے ایواٹار پر کلک کریں، پھر انضمامات پر جائیں۔ موجودہ کمیونٹی کے انضمامات کے صفحات پر ان کمنگ ویب ہکس اور آؤٹ گوئیگ ویب ہکس درج ہیں۔ ہر ویب ہک ایک کمیونٹی سے تعلق رکھتا ہے۔

ڈیفالٹ طور پر، کمیونٹی ایڈمنز اور سسٹم ایڈمنز ویب ہکس بنا سکتے ہیں۔ سسٹم ایڈمن سسٹم کنسول کی پرمیشن ترتیبات میں دوسرے رولز کو یہ حق دے سکتا ہے۔ سسٹم ایڈمن سسٹم کنسول › انضمامات › انٹیگریشن مینجمنٹ میں ہر قسم کو بند بھی کر سکتا ہے: انکمنگ ویب ہکس فعال کریں اور Outgoing Webhooks فعال کریں دونوں ڈیفالٹ طور پر آن ہیں۔

ایک داخلہ ویب ہک بنائیں

1. انضمامات میں، ان کمنگ ویب ہکس منتخب کریں، پھر ان کمنگ ویب ہک شامل کریں پر کلک کریں۔
2. عنوان اور تفصیل درج کریں: یہ صرف انضمامات کے صفحات پر دکھائی دیتے ہیں۔
3. وہ چینل منتخب کریں جس میں پیغامات ڈیفالٹ طور پر جائیں گے۔ ایک ذاتی چینل کے لیے، آپ کو اس کا رکن ہونا ضروری ہے۔
4. اگر بھیجنے والوں کو کہیں اور پوسٹ کرنے کی اجازت نہیں ہونی چاہیے، تو اس چینل کو لاک کریں پر ٹک کریں۔
5. اختیاری طور پر اس کے پیغامات کے لیے صارف نام اور پروفائل تصویر URL مقرر کریں (دیکھیں نام اور آئیکن)۔
6. محفوظ کریں منتخب کریں۔ دکھائی دینے والا URL کاپی کریں: https://chat.example.com/hooks/<key>۔

API کے ذریعے: POST /api/v4/hooks/incoming کے ساتھ {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}؛ response کے id کو key کے طور پر استعمال کریں۔ command line سے: 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 body کے جواب دیتا ہے۔ یہ application/x-www-form-urlencoded کو بھی قبول کرتا ہے جس میں JSON ایک payload field میں ہوتا ہے، جیسا کہ Slack کے ویب ہکس کرتے ہیں، اس لیے Slack کے لیے بنائے گئے tools عام طور پر بغیر تبدیلی کے کام کرتے ہیں۔

ویب ہک کے پوسٹ کردہ ہر پیغام کے نام کے ساتھ بوٹ ٹگ لگتا ہے، چاہے وہ اپنے تخلیق کار کے نام کے نیچے ظاہر ہو، تاکہ لوگ اسے کسی حقیقی شخص کے پیغام سے پہچان سکیں۔ ویب ہک کے پیغامات کبھی خارجہ ویب ہکس کو ٹریگر نہیں کرتے۔

نام اور آئیکن

ویب ہک اس شخص کے طور پر پوسٹ کرتا ہے جس نے اسے بنایا، سوائے اس کے کہ سرور اوور رائڈز کی اجازت دے۔ سسٹم کنسول › انضمامات › انٹیگریشن مینجمنٹ میں دو ترتیبات، جو دونوں ڈیفالٹ طور پر آف ہیں، اسے تبدیل کرتی ہیں:

• انٹیگریشنز کو یوزرنیمز کو اوور رائڈ کرنے کی اجازت دیں (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
  }]
}

کارڈز: مراحل اور چارٹس

Antimatter منسلک فائلوں میں دو فیلڈز شامل کرتا ہے، جو ڈیفالٹ انٹرفیس کے ذریعے دکھائی جاتی ہیں:

• stages: پائپ لائن کے مراحل، جو پیلز (pills) کی صورت میں، زیادہ سے زیادہ 20 تک۔ ہر ایک {"name", "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"}
  }]
}

کلاسیکی انٹرفیس اور دیگر کلائنٹس ان دو فیلڈز کو نظرانداز کرتے ہیں، اس لیے بنیادی معلومات کو text یا fields میں بھی شامل کریں۔

آؤٹ گوئنگ ویب ہک بنائیں

ایک خارجہ ویب ہک کمیونٹی کے عوامی چینلز کی نگرانی کرتا ہے۔ یہ آپ کے URL کو پیغام تب بھیجتا ہے جب پیغام کا پہلا لفظ اس کے ٹریگر ورڈز میں سے ایک سے مماثل ہو، یا جب کوئی شخص پیغام کے مینیو میں اسے منتخب کرے (ایک پیغام کا اقدام)۔

1. انضمامات میں، آؤٹ گوئیگ ویب ہکس منتخب کریں، پھر آؤٹ گوئنگ ویب ہک شامل کریں پر کلک کریں۔
2. عنوان اور تفصیل درج کریں۔
3. درخواست کے Content Type کا انتخاب کریں: application/x-www-form-urlencoded یا application/json۔
4. چینل منتخب کریں، Trigger Words (ہر ایک ایک لائن پر) درج کریں، یا دونوں۔ اگر چینل ہو اور ٹریگر ورڈز نہ ہوں، تو اس چینل کے تمام پیغامات بھیجے جائیں گے۔ اگر دونوں ہوں، تو پیغام دونوں سے مماثل ہونا چاہیے۔
5. Trigger جب کے تحت، پہلا لفظ ٹریگر ورڈ سے بالکل مماثل ہو، پہلا لفظ ٹریگر ورڈ سے شروع ہو، یا پیغام کے مینیو سے منتخب کریں۔ پیغام کے مینیو سے کے ساتھ، ٹریگر ورڈز غائب ہو جاتے ہیں، چینل اختیاری ہوتا ہے (اگر نہ ہو تو یہ اقدام کمیونٹی کے ہر عوامی چینل میں پیش کیا جاتا ہے)، اور عنوان ضروری ہوتا ہے: یہ مینیو میں اقدام کا نام ہے۔
6. کی بیک URLs (ہر لائن پر ایک) درج کریں۔ ہر URL کو ہر مماثل پیغام ملے گا۔
7. اختیاری طور پر جوابات کے لیے صارف نام اور پروفائل تصویر مقرر کریں۔ پیغام کے مینیو سے ایک اقدام کے لیے، آئیکن فیلڈ پروفائل تصویر کی جگہ لیتا ہے: ایک .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 کے ذریعے اپ لوڈ کریں (multipart، فیلڈ image: PNG، JPEG یا GIF، 128 px PNG کے طور پر محفوظ کیا جاتا ہے)؛ اس کے بعد اس کا icon_url GET /api/v4/hooks/outgoing/{hook_id}/icon کی طرف اشارہ کرتا ہے۔

آؤٹ گوئنگ درخواست

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 کے ذریعے پوسٹ کریں۔

پیغام کے اقدامات

پیغام کا ایک ایکشن ایک آؤٹ گوئنگ ویب ہک ہے جس کا Trigger جب پیغام کے مینیو سے پر سیٹ کیا گیا ہو۔ یہ کبھی بھی پوسٹ شدہ پیغامات پر فائر نہیں ہوتا۔ اس کے بجائے، لوگ اسے پیغام کے مینیو میں دیکھتے ہیں: پیغام کے اقدامات (⋯) › مزید اقدامات، انضمامات کے سرخ نیچے، اپنے آئیکن کے ساتھ۔ کلاسیک انٹرفیس پیغام کے اقدامات نہیں دکھاتا۔ اسے منتخب کرنے پر وہ ایک پیغام کال بیک یو آر ایلز کو بھیجا جاتا ہے، اور ایک مختصر اطلاع بھیجا گیا ایکشن کے نام کو دکھاتی ہے، یا آپ کا ephemeral_text دکھایا جاتا ہے۔

• یہ کہاں دکھتا ہے: ویب ہک کے چینل میں، یا چینل کے بغیر، اس کمیونٹی کے ہر عوامی چینل میں۔ صرف عوامی چینلز میں پیغام کے اقدامات ہوتے ہیں۔
• مہمان صرف ان اقدامات تک رسائی حاصل کرتے ہیں جو ان کے اس چینل سے منسلک ہیں، کمیونٹی-وائیڈ اقدامات نہیں۔
• آرکائیو شدہ اور صرف پڑھنے والے چینلز: پیغام اب بھی بھیجا جا سکتا ہے۔ چینل کو آرکائیو کرنے سے اس سے منسلک ویب ہکس حذف ہو جاتے ہیں، اس لیے آرکائیو شدہ چینل میں صرف کمیونٹی-وائیڈ اقدامات باقی رہتے ہیں۔ وہ جواب جسے شخص وہاں پوسٹ نہیں کر سکا، صرف اسے دکھایا جاتا ہے۔
• ریٹ لمٹ: ہر شخص ایک منٹ میں 10 پیغام کے اقدامات چلا سکتا ہے، 5 کے بوسٹ کے بعد۔ اس سے زائد پر، سرور 429 کا جواب دیتا ہے۔
• ذاتی نیٹ ورکس: دیگر آؤٹ گوئنگ ویب ہکس کی طرح، اندرونی ایڈریسز کو غیر مستند اندرونی کنکشنز کی اجازت دیں میں اجازت دی گئی ہونی چاہیے۔

درخواست

پے لوڈ 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 کو 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 شامل ہیں۔ نہ تو ٹوکنز اور نہ ہی کیل بیک یو آر ایلز واپس آتی ہیں۔
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: کسی ایسے پیغام پر ایکشن چلاتا ہے جسے آپ پڑھ سکتے ہیں۔ یہ {"ephemeral_text"} کے ساتھ جواب دیتا ہے۔

جب ویب ہک کام نہ کرے

• 501 from the hook URL: سروسر پر آئنگوئنگ ویب ہکس بند ہیں۔
• 400 "Failed to decode the payload…": JSON درست نہیں ہے، یا فارم فیلڈ کا نام payload نہیں ہے۔ "No text specified." کا مطلب ہے کہ درخواست میں نہ تو text ہے اور نہ attachments۔
• 403: ویب ہک کسی اور چینل کے لیے لاک ہے، یا اس کے مالک اب چینل نہیں پڑھ سکتے۔
• آؤٹ گوئنگ ویب ہک کبھی فائر نہیں ہوتا: چینل ذاتی ہے، ٹریگر پہلا لفظ نہیں ہے، پیغام کسی ویب ہک سے آیا ہے، یا ویب ہک کو پیغام کے مینیو سے فائر ہونے کے لیے سیٹ کیا گیا ہے۔
• پیغام ایکشن مینیو میں موجود نہیں: چینل ذاتی ہے، ایکشن کسی دوسرے چینل سے منسلک ہے، شخص مہمان ہے اور ایکشن کو کوئی چینل نہیں، یا آؤٹ گوئنگ ویب ہکز بند ہیں۔
• پیغام ایکشن چلانے پر 404: ایکشن موجود نہیں ہے، یا وہ اس شخص کے لیے اس پیغام کے چینل کو کور نہیں کرتا۔ 429: شخص نے ایک منٹ میں 10 سے زیادہ ایکشنز چلا دیے۔ 502: کوئی بھی کیل بیک یو آر ایل رسائی میں نہیں آ سکی (وجہ لاگ میں موجود ہے)۔
• لاگز: ویب ہک ڈیبگنگ کو فعال کریں (LogSettings.EnableWebhookDebugging) کو آن کرنے پر، اور لاگ لیول کو DEBUG پر رکھنے پر، سرور ناکام داخلہ طلبیوں کے پیلوڈز کو لاگ کرتا ہے۔ ناکام خارجہ کالز کو Outgoing Webhook POST failed کے طور پر لاگ کیا جاتا ہے۔