האם פריוריטי תומכת ב-Webhooks?

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

איך מאומת webhook של פריוריטי?

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

האם פריוריטי מנסה לשלוח שוב webhook שנכשל?

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

כמה זמן פריוריטי שומרת שגיאות webhook?

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

האם webhook של פריוריטי צריך לשאת את המסמך המלא או רק מזהה?

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

Webhooks בפריוריטי - יהונתן סעדיה

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

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

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

שני אובייקטים, לא אחד

זו נקודת הבלבול הראשונה. "Webhook" בפריוריטי אינו דבר אחד:

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

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

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

איפה בדיוק מחברים את הכלל

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

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

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

מה בדיוק מגיע אליך

כותרות

הקריאה היוצאת נושאת כותרות מטא-דאטה שמזהות מה בדיוק קרה:

priority-form-name - שם הטופס שממנו נשלח
priority-bpm-subject - נושא ה-BPM
priority-bpm-id ו-priority-bpm-name - מזהה ושם הכלל
priority-bpm-token - טוקן האימות

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

גוף הבקשה

ה-JSON מכיל את השדות שבחרת בכלל, מאורגנים לפי טופס או טבלה:

{
  "DOCUMENTS_P": { "PDOCNO": "SH2000000880", "CDES": "David Smith" },
  "DOCTODOLIST": { "OWNERLOGIN": "SteveD" }
}

המבנה הזה קובע החלטה תכנונית: ה-webhook נושא רק את מה שבחרת מראש. הוא לא מביא את המסמך המלא. בפועל יש שתי גישות:

Thin webhook - לשלוח רק את מזהה המסמך, ואז למשוך את המסמך המלא דרך ה-REST API. יותר קריאות, אבל תמיד עדכני ועמיד לשינויי מבנה.
Fat webhook - לשלוח את כל השדות הדרושים בגוף. פחות קריאות, אבל כל שדה חדש דורש עריכה של הכלל בפריוריטי.

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

הבעיה האמיתית: אין ניסיון חוזר מתועד

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

מכאן נגזרות שלוש הנחיות:

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

webhook בלי תהליך השלמה הוא לא אינטגרציה אמינה, הוא אופטימיזציה. הרבה פרויקטים מגלים את זה מאוחר מדי.

יומן השגיאות

מגרסה 26.0 קיים Webhook - Error Log, באותו תפריט תחזוקת BPM. הוא שומר 7 ימים בלבד.

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

מאותה גרסה יש גם שדות URL - Cont. ו-URL - Cont. (2), שמאפשרים כתובת ארוכה מהמגבלה של שדה בודד. אם יש לך כתובת עם נתיב ארוך או פרמטרים, זה הפתרון.

מתי webhooks ומתי תשאול

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

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

Webhooks בפריוריטי: לדחוף אירועים החוצה במקום לתשאל בלולאה

עיקרי הדברים