Webhooks

Webhook נכנס מאפשר למערכת אחרת לפרסם הודעה בערוץ על ידי שליחת JSON לכתובת סודית. Webhook יוצא עושה את ההפך: הוא שולח הודעות לכתובת שלך, אלו שמתחילות במילה טריגר או אלו שנבחרו על ידי המשתמש בתפריט ההודעה, ומפרסם את התשובה שלך.

מקום לניהול Webhooks

פתח את האייקון שלך בפינה הימנית העליונה, ואז אינטגרציות. עמודי האינטגרציות של הקהילה הנוכחית מציגים Webhooks נכנסים ו-Webhooks יוצאים. כל Webhook שייך לקהילה אחת.

By default, community admins and system admins can create webhooks. A system admin can give the right to other roles in the permission settings of the System Console. A system admin can also turn each kind off in System Console › Integrations › Integration Management: Enable Incoming Webhooks and Enable Outgoing Webhooks are both on by default.

יצירת Webhook נכנס

1. ב-אינטגרציות, בחר Webhooks נכנסים, ואז הוספת Webhook נכנס.
2. מלא כותרת ו-תיאור: הם מופיעים רק בעמודי האינטגרציות.
3. בחר את ערוץ אליו ההודעות נשלחות כברירת מחדל. עבור ערוץ פרטי, עליך להיות חבר בו.
4. סמן נעילה לערוץ זה אם השולחים לא יכולים לפרסם במקומות אחרים.
5. אופציונלי, הגדר שם משתמש ו-URL ל-תמונת פרופיל עבור ההודעות שלו (ראה שם ואייקון).
6. בחר שמירה. העתק את הכתובת המוצגת: https://chat.example.com/hooks/<key>.

עם 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".

שליחת הודעה ל-Webhook נכנס

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, בדומה ל-Webhooks של Slack, כך שכלים שנועדו ל-Slack עובדים בדרך כלל ללא שינויים.

כל הודעה ש-Webhook שולח נושאת תג בוט ליד שמה, גם כאשר היא מוצגת תחת שם היוצר, כדי שאנשים יוכלו להבחין בינה ובין הודעה של אדם אמיתי. הודעות Webhook לעולם לא מפעילות Webhooks יוצאים.

שם ואייקון

Webhook שולח בשם האדם שייצר אותו, אלא אם כן השרת מאפשר החלפות. שתי הגדרות בקונסולת מערכת › אינטגרציות › ניהול אינטגרציות, שתיהן כבויות כברירת מחדל, משנות זאת:

• אפשרות להחלפת שמות משתמשים על ידי אינטגרציות (ServiceSettings.EnablePostUsernameOverride): מוצג שם השם משתמש של ה-Webhook או ערך username בבקשה; אם אין שניהם, השם הוא webhook.
• הרשאה לאינטגרציות להחליף את אייקון תמונת הפרופיל (ServiceSettings.EnablePostIconOverride): תמונת הפרופיל של ה־Webhook, או icon_url או icon_emoji מהבקשה, מוצגים.

ערך מהבקשה גובר על הערך שמאוחסן ב-Webhook.

קבצים מצורפים

קבצים מצורפים מוסיפים תוכן מבני מתחת לטקסט. הם עוקבים אחר פורמט קבצים מצורפים של 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: שלבי צינור כגלגליים, עד 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.

יצירת Webhook יוצא

Webhook יוצא עוקב אחר הערוצים הציבוריים של קהילה. הוא שולח הודעה לכתובת שלך כאשר המילה הראשונה בהודעה תואמת אחת ממילות הטריגר, או כאשר מישהו בוחר אותו מתפריט ההודעה (פעולה בהודעה).

1. באינטגרציות, בחרו Webhooks יוצאים, ואז הוספת Webhook יוצא.
2. מלאו את הכותרת ואת התיאור.
3. בחרו את סוג התוכן של הבקשה: application/x-www-form-urlencoded או application/json.
4. בחרו ערוץ, הזינו מילות טריגר (מילה בשורה), או את שניהם. אם יש ערוץ בלי מילות טריגר, כל הודעה בערוץ נשלחת. אם יש שניהם, ההודעה חייבת להתאים לשניהם.
5. תחת טריגר כאשר, בחרו המילה הראשונה תואמת במדויק מילה מפתח, המילה הראשונה מתחילה במילה מפתח, או מתפריט ההודעה. אם בחרתם מתפריט ההודעה, מילות הטריגר נעלמות, הערוץ הוא אופציונלי (בלי ערוץ, הפעולה מוצעת בכל ערוץ ציבורי בקהילה), והכותרת היא חובה: היא שם הפעולה בתפריט.
6. הזינו את כתובות קריאה חוזרת (שורה לכל כתובת). כל כתובת מקבלת כל הודעה מתאימה.
7. ניתן להגדיר באופן אופציונלי את שם המשתמש ואת תמונת הפרופיל שישמשו לתשובות. עבור פעולה מתפריט ההודעה, השדה Icon מחליף את תמונת הפרופיל: כתובת URL של קובץ .png או .jpg או, בממשק ברירת המחדל של Antimatter, תמונה שהועלתה. התפריט מציג אותה בגוון אפור; אם אין כזו, לפעולה תינתן אייקון ניטרלי.
8. בחרו בשמירה והעתיקו את האסימון (token) המוצג. השירות שלכם משתמש בו כדי לוודא שהבקשות מגיעות מהשרת שלכם.

באמצעות 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 ל"מתפריט ההודעה"). Webhook עם trigger_when 2 אינו דורש מילות טריגר ודורש display_name. העלו את האייקון שלו עם POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, שדה image: PNG, JPEG או GIF, נשמר כ-PNG בגודל 128 פיקסלים); icon_url שלו מצביע אז על GET /api/v4/hooks/outgoing/{hook_id}/icon.

הבקשה היוצאת

Antimatter שולח POST עם השדות הבאים, כ-JSON או כ-form-encoded בהתאם לסוג התוכן:

{
  "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 עם האסימון (token) של ה-Webhook לפני כל פעולה. בגרסת form-encoded, timestamp הוא בשניות ולא במילי-שניות. השרת ממתין לתשובתכם עד לתום הזמן המוגדר בתום זמן לבקשות אינטגרציה (30 שניות כברירת מחדל, ServiceSettings.OutgoingIntegrationRequestsTimeout).

תשובה ל-Webhook יוצא

כדי לפרסם תשובה, ענו עם 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: מוצגים כאשר השרת מאפשר החלפות; אחרת נעשה שימוש בערכים של ה-Webhook עצמו.
• props, type, priority: כפי שמוגדר עבור Webhooks נכנסים.

התשובה מפורסמת בשם יוצר ה-Webhook, או בשם המותאם אם קיים. לכל תוכן ארוך מענה קצר, ענה מיד ופרסם מאוחר יותר באמצעות Webhook נכנס או ה-API.

פעולות הודעה

פעולת הודעה היא Webhook יוצא ששדה טריגר כאשר מוגדר למתפריט ההודעה. היא לעולם לא מופעלת על הודעות שפורסמו. במקום זאת, המשתמשים רואים אותה בתפריט ההודעה: פעולות הודעה (⋯) › פעולות נוספות, תחת הכותרת אינטגרציות, יחד עם האייקון שלה. הממשק הקלאסי אינו מציג פעולות הודעה. בחירה בפעולה שולחת את ההודעה הספציפית הזו לכתובות ה-Callback, וההודעה הקצרה מציגה נשלח אל שם הפעולה, או מציגה את ephemeral_text שלך.

• מקום ההצגה: בערוץ של ה-Webhook, או, אם אין ערוץ, בכל ערוץ ציבורי בקהילה. רק לערוצים ציבוריים יש פעולות הודעה.
• אורחים מקבלים רק את הפעולות המצומדות לערוץ שבו הם נמצאים, ולא את הפעולות הרחבות לקהילה.
• ערוצים בארכיון ובלבד לקריאה: ההודעה עדיין יכולה להישלח. העברת ערוץ לארכיון מחזיקה את ה-Webhooks המצומדים אליו, כך שערוץ בארכיון שומר רק על הפעולות הרחבות לקהילה. תשובה שהמשתמש לא יכול היה לפרסם שם מוצגת לו בלבד.
• מגבלת קצב: כל משתמש יכול להפעיל 10 פעולות הודעה בדקה, אחרי זינוק של 5. מעל לזה, השרת מענה 429.
• רשתות פרטיות: כמו ב-Webhooks יוצאים אחרים, כתובות פנימיות חייבות להיות מורשות באפשרות חיבורים פנימיים לא אמורים אל.

הבקשה

ה-Payload נשלח כ-JSON או כ-Form-encoded, בהתאם לסוג התוכן של ה-Webhook:

{
  "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.
• ב-Form-encoded, הקבצים מגיעים כשדות חוזרים של file_id, file_name ו-file_link, באותה סדרה.

התשובה

מענים כפי שמענים לכל Webhook יוצא (ראו תשובה ל-Webhook יוצא): 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. לא מוחזרים אסימונים או כתובות callback.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: מריץ פעולה על הודעה שניתן לקרוא. הוא מענה {"ephemeral_text"}.

כש-Webhook לא עובד

• 501 מכתובת ה-hook: Webhooks נכנסים כבוים על השרת.
• 400 "Failed to decode the payload…": ה-JSON לא תקין, או ששדה הטופס לא נקרא payload. "No text specified." פירושו שהבקשה אינה מכילה לא text ולא attachments.
• 403: ה-Webhook נעול לערוץ אחר, או שהבעלים שלו כבר לא יכול לקרוא את הערוץ.
• Webhook יוצא nie מריץ: הערוץ פרטי, המפעיל אינו המילה הראשונה, ההודעה הגיעה מ-Webhook, או שה-Webhook מוגדר להפעלה From the message menu.
• פעולת הודעה אינה בתפריט: הערוץ פרטי, הפעולה קשורה לערוץ אחר, האדם הוא אורח והפעולה אינה בעלת ערוץ, או ש-Webhooks יוצאים כבוים.
• 404 בעת הרצת פעולת הודעה: הפעולה אינה קיימת, או שהיא אינה מכסה את הערוץ של ההודעה עבור האדם הזה. 429: האדם הרץ יותר מ-10 פעולות בדקה. 502: אף אחת מכתובות ה-callback לא הושגה (הסיבה מופיעה ביומן).
• יומן: עם הפעלת ניפוי Webhook דלוקה (LogSettings.EnableWebhookDebugging), ורמת היומן על DEBUG, השרת רושם את ה-payloads של בקשות נכנסות ששגו. קריאות יוצאות ששגו נרשמות כ-Outgoing Webhook POST failed.