#שילוב Webhook בתהליך עבודה

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

#סקירה כללית

Webhook הוא מנגנון "API הפוך" המאפשר למערכות חיצוניות לשלוח נתונים באופן יזום ל-NocoBase כאשר מתרחשים אירועים ספציפיים. בהשוואה לסקר פעיל (polling), Webhook מציע גישת שילוב בזמן אמת ויעילה יותר.

#תרחישי שימוש אופייניים

#שליחת נתוני טפסים

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

#התראות הודעות

אירועים מפלטפורמות הודעות של צד שלישי (כמו WeCom, DingTalk, Slack) – למשל, הודעות חדשות, אזכורים (@) או השלמת אישורים – יכולים להפעיל תהליכי עבודה אוטומטיים ב-NocoBase באמצעות Webhooks.

#סנכרון נתונים

כאשר נתונים משתנים במערכות חיצוניות (כמו CRM, ERP), Webhooks דוחפים עדכונים ל-NocoBase בזמן אמת כדי לשמור על סנכרון הנתונים.

#שילוב שירותי צד שלישי

• GitHub: אירועי דחיפת קוד, יצירת בקשות משיכה (PR) מפעילים תהליכי עבודה אוטומטיים.
• GitLab: התראות סטטוס של תהליכי CI/CD.
• שליחת טפסים: מערכות טפסים חיצוניות שולחות נתונים ל-NocoBase.
• התקני IoT: שינויים בסטטוס התקנים, דיווח נתוני חיישנים.

#תכונות

#מנגנון טריגר גמיש

• תומך בשיטות HTTP כגון GET, POST, PUT, DELETE.
• מנתח אוטומטית פורמטים נפוצים כמו JSON ונתוני טפסים.
• אימות בקשות הניתן להגדרה, כדי להבטיח מקורות מהימנים.

#יכולות עיבוד נתונים

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

#אבטחה מובטחת

• תומך באימות חתימה למניעת בקשות מזויפות.
• רשימת היתרים (whitelist) של כתובות IP הניתנת להגדרה.
• העברת נתונים מוצפנת באמצעות HTTPS.

#שלבי שימוש

#1. התקנת תוסף

מצאו והתקינו את התוסף תהליך עבודה: טריגר Webhook במנהל התוספים.

שימו לב: זהו תוסף מסחרי הדורש רכישה או מנוי נפרדים.

#2. יצירת תהליך עבודה מסוג Webhook

1. עברו לדף ניהול תהליכי עבודה.
2. לחצו על יצירת תהליך עבודה.
3. בחרו בטריגר Webhook כסוג הטריגר.

4. הגדירו את פרמטרי ה-Webhook.

• נתיב בקשה: נתיב URL מותאם אישית ל-Webhook.
• שיטת בקשה: בחרו את שיטות ה-HTTP המותרות (GET/POST/PUT/DELETE).
• סינכרוני/אסינכרוני: בחרו אם להמתין לסיום ביצוע תהליך העבודה לפני החזרת התוצאות.
• שיטת אימות: הגדירו אימות חתימה או מנגנוני אבטחה אחרים.

#3. הגדרת צמתי תהליך עבודה

הוסיפו צמתי תהליך עבודה בהתאם לדרישות העסקיות שלכם, לדוגמה:

• פעולות על אוספים: יצירה, עדכון, מחיקת רשומות.
• היגיון מותנה: פיצול מותנה בהתאם לנתונים שהתקבלו.
• בקשת HTTP: קריאה ל-API אחרים.
• התראות: שליחת מיילים, הודעות SMS ועוד.
• קוד מותאם אישית: הפעלת קוד JavaScript.

#4. קבלת כתובת ה-Webhook

לאחר יצירת תהליך העבודה, המערכת תיצור כתובת Webhook ייחודית, בדרך כלל בפורמט הבא:

https://your-nocobase-domain.com/api/webhooks/your-workflow-key

#5. הגדרה במערכת צד שלישי

הגדירו את כתובת ה-Webhook שנוצרה במערכת צד שלישי:

• הגדירו את כתובת ה-callback לשליחת נתונים במערכות טפסים.
• הגדירו Webhook ב-GitHub/GitLab.
• הגדירו את כתובת דחיפת האירועים ב-WeCom/DingTalk.

#6. בדיקת ה-Webhook

בדקו את ה-Webhook באמצעות כלים (כמו Postman, cURL):

curl -X POST https://your-nocobase-domain.com/api/webhooks/your-workflow-key \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"message":"Hello NocoBase"}}'

#גישה לנתוני בקשה

בתהליכי עבודה, תוכלו לגשת לנתונים שהתקבלו מה-Webhook באמצעות משתנים:

• {{$context.data}}: נתוני גוף הבקשה.
• {{$context.headers}}: מידע כותרות הבקשה.
• {{$context.query}}: פרמטרי שאילתת URL.
• {{$context.params}}: פרמטרי נתיב.

#הגדרות תגובה

#מצב סינכרוני

מחזיר תוצאות לאחר השלמת ביצוע תהליך העבודה, וניתן להגדרה:

• קוד סטטוס תגובה: 200, 201 ועוד.
• נתוני תגובה: נתוני JSON מותאמים אישית שיוחזרו.
• כותרות תגובה: כותרות HTTP מותאמות אישית.

#מצב אסינכרוני

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

• תהליכי עבודה ארוכי טווח.
• תרחישים שאינם דורשים החזרת תוצאות ביצוע.
• תרחישי עומס גבוה (High-concurrency).

#שיטות עבודה מומלצות לאבטחה

#1. הפעלת אימות חתימה

רוב שירותי צד שלישי תומכים במנגנוני חתימה:

// Example: Verify GitHub Webhook signature
const crypto = require('crypto');
const signature = context.headers['x-hub-signature-256'];
const payload = JSON.stringify(context.data);
const secret = 'your-webhook-secret';
const expectedSignature = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expectedSignature) {
  throw new Error('Invalid signature');
}

#2. שימוש ב-HTTPS

ודאו ש-NocoBase פרוסה בסביבת HTTPS כדי להגן על אבטחת העברת הנתונים.

#3. הגבלת מקורות בקשה

הגדירו רשימת היתרים (whitelist) של כתובות IP, כדי לאפשר בקשות רק ממקורות מהימנים.

#4. אימות נתונים

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

#5. תיעוד ביקורת (Audit Logging)

תיעוד כל בקשות ה-Webhook, כדי להקל על מעקב ופתרון בעיות.

#פתרון בעיות נפוצות

#ה-Webhook לא מופעל?

1. ודאו שכתובת ה-Webhook נכונה.
2. ודאו שסטטוס תהליך העבודה הוא "מופעל".
3. בדקו את יומני השליחה של מערכת צד שלישי.
4. בדקו את הגדרות חומת האש והרשת.

#כיצד לפתור בעיות ב-Webhooks?

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

#כיצד לטפל בניסיונות חוזרים (Retries)?

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

• ודאו שתהליך העבודה הוא אידמפוטנטי (idempotent).
• השתמשו במזהים ייחודיים למניעת כפילויות.
• תיעוד מזהי בקשות שכבר טופלו.

#טיפים לאופטימיזציית ביצועים

• השתמשו במצב אסינכרוני לטיפול בפעולות גוזלות זמן.
• הוסיפו היגיון מותנה כדי לסנן בקשות שאינן דורשות טיפול.
• שקלו להשתמש בתורי הודעות (message queues) לטיפול בתרחישי עומס גבוה.

#תרחישי דוגמה

#עיבוד שליחת טופס חיצוני

// 1. Verify data source
// 2. Parse form data
const formData = context.data;

// 3. Create customer record
// 4. Assign to relevant owner
// 5. Send confirmation email to submitter
if (formData.email) {
  // Send email notification
}

#התראת דחיפת קוד ב-GitHub

// 1. Parse push data
const commits = context.data.commits;
const branch = context.data.ref.replace('refs/heads/', '');

// 2. If main branch
if (branch === 'main') {
  // 3. Trigger deployment process
  // 4. Notify team members
}

#משאבים קשורים

• תיעוד תוסף תהליך עבודה
• תהליך עבודה: טריגר Webhook
• תהליך עבודה: צומת בקשת HTTP
• אימות באמצעות מפתחות API