Webhooks — אירועי מודרציה בזמן אמת במערכות שלכם

1מה webhooks עושים

במקום לתשאל את ה-API, אתם רושמים כתובת URL ו-Telm שולחת אליה HTTP POST חתום בכל פעם שמשהו קורה בקבוצה שלכם. כך אתם מכניסים אירועי מודרציה למערכות שלכם — לוח בקרה, מחסן נתונים, ערוץ התראות — בזמן אמת.

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

2מדוע דחיפה עדיפה על תשאול

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

שימושים אופייניים כוללים שיקוף חסימות לכלי הניהול שלכם, התראה לערוץ צוות כאשר מזוהה פשיטה, הזרמת זיהויים לאנליטיקה, או הפעלת תהליך עבודה כאשר חבר מצטרף או עוזב.

• בזמן אמת: אתם לומדים על אירוע כשהוא קורה, לא בתשאול הבא שלכם.
• יעיל: אין קריאות חוזרות שאוכלות מהמכסה היומית שלכם.
• שלם: מסירות מנוסות שוב, כך שהשבתה קצרה בצד שלכם אינה מאבדת אירועים.

3אירועים שאפשר להירשם אליהם

יש שבעה סוגי אירועים שאפשר להירשם אליהם, המכסים פסקי דין של ספאם, עונשים ושינויי חברות. הודעה יחידה שעברה מודרציה יכולה להפיק יותר מאירוע אחד — הודעת ספאם שמסתיימת בחסימה מפיקה גם spam.detected וגם user.banned.

• spam.detected — המנוע סימן הודעה כספאם.
• message.suspicious — זיהוי צל (מצב ניטור) עם ציון.
• user.banned — חבר נחסם.
• user.kicked — חבר הוסר.
• user.muted — חבר הושתק.
• user.joined — חבר הצטרף לקבוצה.
• user.left — חבר עזב את הקבוצה.

4מעטפת המטען

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

• id — מזהה מסירה ייחודי; מסירות חוזרות של אותו אירוע עושות שימוש חוזר באותו מזהה, וכך אתם מבטלים כפילויות.
• type — סוג האירוע, אחד מהשבעה לעיל.
• created_at — מתי האירוע הופעל, ב-RFC3339 UTC.
• group_id — הקבוצה שאליה שייך האירוע (כאשר רלוונטי).
• data — אובייקט ספציפי לאירוע: פרטי הודעה ופסק דין עבור אירועי ספאם, פרטי חבר עבור אירועי חברות.

5אימות שמסירות באמת מגיעות מ-Telm

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

החתימה היא HMAC-SHA256 של חותמת הזמן וגוף הבקשה הגולמי, ממופתחת עם סוד החתימה של נקודת הקצה שלכם. כדי לאמת, חשבו מחדש את ה-HMAC על כותרת חותמת הזמן ועל הבתים המדויקים שקיבלתם, והשוו אותו לכותרת החתימה.

• X-Telm-Signature — החתימה, בפורמט v1 ואחריו ה-HMAC-SHA256 בהקסדצימלי של חותמת הזמן מחוברת לגוף.
• X-Telm-Timestamp — חותמת הזמן בשניות-יוניקס שנחתמת, כך שתוכלו לדחות מסירות ישנות או משוחזרות.
• X-Telm-Event — סוג האירוע, ו-X-Telm-Delivery — מזהה המסירה לביטול כפילויות.
• סוד החתימה מוצג פעם אחת כשאתם יוצרים את נקודת הקצה ומתחיל ב-whsec_. אחסנו אותו בבטחה; הוא הדבר היחיד שמוכיח שמסירה אמיתית.

6מסירה אמינה ונטולת כפילויות

המסירה היא לפחות-פעם-אחת: Telm מוודאת שאירוע מגיע אליכם, מה שאומר שאותו אירוע יכול מדי פעם להגיע פעמיים. מכיוון שכל מסירה חוזרת עושה שימוש חוזר באותו מזהה מסירה, אתם מבטלים כפילויות על ידי אחסון המזהים שעיבדתם ודילוג על חזרות.

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

• הגיבו במהירות עם סטטוס 2xx; בצעו עבודה כבדה באופן אסינכרוני לאחר האישור.
• בטלו כפילויות לפי מזהה המסירה — לעולם לא לפי תוכן המטען.
• נקודת קצה שנכשלת כעשרים פעמים ברציפות ללא הצלחה בתוך חלון של 72 שעות מושבתת אוטומטית; הפעילו אותה מחדש כשהשרת שלכם תקין.

7ניהול נקודות קצה וקריאת היומן

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

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

• צרו נקודת קצה והעתיקו את סוד ה-whsec_ מיד.
• שלחו ping לבדיקה כדי לאמת את בדיקת החתימה שלכם מקצה לקצה.
• הגבילו נקודת קצה לקבוצה אחת או השאירו אותה פתוחה לכל הקבוצות שאתם מנהלים.
• קראו את יומן המסירות כדי לבחון ניסיונות אחרונים ואת תוצאותיהם.

8שיטות עבודה מומלצות וטעויות נפוצות

מקבל חסון עוקב אחר כמה כללים שמונעים את הבעיות הנפוצות ביותר.

• אמתו את החתימה על בתי הגוף הגולמיים — ניתוח ל-JSON תחילה וסריאליזציה מחדש עלולים לשנות את הבתים ולשבור את הבדיקה.
• החזירו 2xx מהר ועבדו מאוחר יותר; מטפל איטי גורם לפסקי זמן ולניסיונות חוזרים מיותרים.
• הפכו את הטיפול לאידמפוטנטי כך שאירוע שנמסר מחדש לא ייספר פעמיים.
• השתמשו ב-HTTPS בכתובת URL שנגישה לציבור; Telm חוסמת כתובות פנימיות ופרטיות ואינה עוקבת אחר הפניות.
• שמרו את סוד ה-whsec_ מחוץ ליומנים ולקוד הלקוח.