Telm יכולה לדחוף אירועי מודרציה לשרת שלכם בזמן אמת. אתם רושמים נקודת קצה, בוחרים אילו אירועים לקבל, ו־Telm שולחת POST חתום עבור כל אחד. כל מסירה נושאת חתימת HMAC-SHA256 שאתם מאמתים עם סוד נקודת הקצה שלכם. מסירות שנכשלו נשלחות שוב לפי לוח זמנים; נקודת קצה בלתי־ניתנת־להשגה לצמיתות מושבתת אוטומטית.
1מעטפת האירוע
כל webhook הוא HTTP POST עם גוף JSON במעטפת משותפת. למעטפת יש id (מזהה מסירה ייחודי למניעת כפילויות), type (שם האירוע), חותמת זמן created_at, ה־group_id שאליו האירוע שייך, ואובייקט data שצורתו תלויה בסוג האירוע.
ה־id דטרמיניסטי עבור אירועים אמיתיים, כך שאם אותו אירוע נמסר פעמיים — למשל לאחר ניסיון חוזר — אתם מקבלים את אותו id בשני המקרים. השתמשו בכותרת X-Telm-Delivery (המשקפת id זה) כמפתח אידמפוטנטיות כדי שהמטפל שלכם יעבד כל אירוע פעם אחת בלבד.
- שדות המעטפת: id, type, created_at, group_id, data.
- type הוא אחד משמות האירועים מהקטלוג שלהלן.
- data נושא את השדות הספציפיים לאירוע.
- השתמשו ב־id (ובכותרת X-Telm-Delivery) כדי למנוע כפילויות בניסיונות חוזרים.
2קטלוג אירועים
אתם רושמים נקודת קצה לכל תת־קבוצה מהקטלוג. spam.detected נורה כשהמנוע מסמן הודעה כספאם. message.suspicious נורה במצב ניטור, כשהמנוע היה פועל אך רק ניקד את ההודעה בצל. אירועי החברים מכסים אנשים שנכנסים, עוזבים ונענשים.
אירוע ה־ping מיוחד: הוא אינו חלק מהקטלוג הניתן להרשמה ונשלח רק כשאתם מפעילים מסירת בדיקה לנקודת קצה, כך שתוכלו לאשר שהמקלט ובדיקת החתימה שלכם עובדים מקצה לקצה.
- spam.detected — הודעה סווגה כספאם.
- message.suspicious — זיהוי צל (מצב ניטור).
- user.banned, user.kicked, user.muted — הופעלה פעולת מודרציה.
- user.joined, user.left — חבר נכנס או עזב את הקבוצה.
- ping — אירוע בדיקה ידני, לעולם אינו נורה על ידי פעילות אמיתית.
3שדות ה־payload לכל אירוע
עבור spam.detected ו־message.suspicious, אובייקט ה־data נושא message_id, user_id, username, טקסט ההודעה (מקוצר עבור הודעות ארוכות מאוד), הפעולה שננקטה, קטגוריה, סיבה, השפה שזוהתה, וניקוד ביטחון. message.suspicious נושא בנוסף את ניקוד הצל.
עבור אירועי החברים (user.joined, user.left, user.banned, user.kicked, user.muted), אובייקט ה־data נושא user_id, username, first_name, message_id אופציונלי, וסיבה במקום שבו היא חלה. אירוע בסיסי אחד יכול להפיק יותר מ־webhook אחד — הודעת ספאם שמפעילה חסימה נמסרת גם כ־spam.detected וגם כ־user.banned.
- אירועי ספאם: message_id, user_id, username, text, action, category, reason, language, confidence (בתוספת score עבור message.suspicious).
- אירועי חברים: user_id, username, first_name, message_id, reason.
- אירוע בודד עשוי לפלוט כמה אירועים; קשרו ביניהם לפי user_id ו־group_id.
4אימות חתימת ה־HMAC
כל מסירה חתומה כדי שתוכלו להיות בטוחים שהיא באמת הגיעה מ־Telm ולא שובשה. אתם מקבלים סוד נקודת קצה (הוא מתחיל ב־whsec_) פעם אחת, כשאתם יוצרים את נקודת הקצה. אחסנו אותו והשתמשו בו כדי לאמת כל בקשה נכנסת.
כדי לאמת, קחו את ערך כותרת X-Telm-Timestamp, הוסיפו נקודה, ואז הוסיפו את גוף הבקשה הגולמי המדויק, וחשבו HMAC-SHA256 של אותה מחרוזת באמצעות סוד נקודת הקצה שלכם כמפתח. קודדו את התוצאה ב־hex והוסיפו לפניה קידומת v1= — היא חייבת להיות שווה לכותרת X-Telm-Signature. השוו עם השוואה בזמן קבוע, ודחו את הבקשה אם חותמת הזמן ישנה מכמה דקות (חמש היא נקודת חתך טובה) כדי לחסום שידורים חוזרים.
- X-Telm-Event — סוג האירוע.
- X-Telm-Delivery — מזהה המסירה (מפתח אידמפוטנטיות).
- X-Telm-Timestamp — שניות unix, חתום כדי למנוע שידורים חוזרים.
- X-Telm-Signature — v1= בתוספת HMAC-SHA256 ב־hex של חותמת הזמן, נקודה, והגוף הגולמי.
5מסירה, ניסיונות חוזרים והשבתה אוטומטית
מסירה נחשבת מוצלחת רק אם נקודת הקצה שלכם מגיבה בסטטוס 2xx. כל דבר אחר — קוד שאינו 2xx, פסק זמן, או שגיאת חיבור — נחשב לכישלון ונשלח שוב לפי לוח זמנים קבוע: מיד, ואז לאחר דקה, 5 דקות, 30 דקות, שעתיים ו־6 שעות, עבור שישה ניסיונות המשתרעים על פני כשמונה וחצי שעות לפני שהמסירה נסגרת ככושלת.
אם נקודת קצה ממשיכה להיכשל — לפחות עשרים כשלונות רצופים ללא מסירה מוצלחת במשך שלושה ימים — Telm משביתה אותה אוטומטית כדי שתפסיק לשלוח לכתובת מתה. אתם יכולים להפעיל אותה מחדש מלוח הבקרה ברגע שהמקלט שלכם בריא שוב.
- הצלחה = HTTP 2xx. הגיבו מהר (תוך כעשר שניות) ובצעו עבודה כבדה באופן אסינכרוני.
- לוח ניסיונות חוזרים: מיד, +1 דקה, +5 דקות, +30 דקות, +שעתיים, +6 שעות (שישה ניסיונות).
- מושבתת אוטומטית לאחר 20 כשלונות רצופים ללא הצלחה תוך 72 שעות.
- רישום webhooks דורש את תוכנית Pro ומעלה.