איך לבנות Webhooks אמינים של Microsoft Graph עבור SharePoint ו-M365

By Mirko Peters · 2025-11-16

בניית Webhooks אמינים של Microsoft Graph עבור SharePoint ו-M365 עם אימות מאובטח, חידוש אוטומטי של מנויים ומסירת התראות חסינה.

Automatically translated with AI from the original post. Read the English original

בניית Webhooks אמינים של Microsoft Graph עבור SharePoint ו-M365 יכולה לאתגר גם מפתחים מנוסים. ייתכנו בעיות כמו כשל באימות, אם נקודת הקצה שלכם אינה מחזירה את אסימון האימות או אינה מגיבה עם סטטוס 200 OK. בין הבעיות הנפוצות: נקודות קצה שנחסמות על ידי חומות אש, שגיאות תצורה ברשת או הפרעות של תוכנת ביניים (middleware). ניסיונות חוזרים שהחמיצו ומנויים שפגו מופיעים לרוב כאשר השירות אינו מקבל את בקשת האימות, או כאשר נקודות הקצה אינן נגישות מהאינטרנט. בהמשך תלמדו כיצד להימנע מהמכשולים האלה ולבנות צינור התראות חזק ומאובטח, יחד עם רשימת בדיקה מעשית ושיטות עבודה מומלצות.

עיקרי הדברים

• Webhooks של Microsoft Graph מספקים התראות בזמן אמת על שינויים ב-Microsoft 365, וכך מייתרים את הצורך בשאילתות חוזרות ונשנות (polling).

• ודאו שנקודת הקצה של ה-webhook נגישה מהאינטרנט ומשתמשת ב-HTTPS כדי לשמור על אבטחה ואמינות.

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

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

• אוטומטו את חידוש המנויים וניטרו את צינור ה-webhook כדי להבטיח התראות רציפות ואמינות.

יסודות Webhooks של Microsoft Graph

מהם Webhooks של Microsoft Graph

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

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

ניתן להגדיר התראות עבור סוגים רבים של אירועים, למשל:

• הודעות

• אירועים

• אנשי קשר

• משתמשים

• קבוצות

• שיחות

• קבצים ב-OneDrive

• התראות

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

מדוע אמינות חשובה

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

עם זאת, בעיות אמינות עלולות לגרום לנזק משמעותי:

• כשלים ב-webhooks עלולים לפגוע בתפקוד היישום אם לא מטפלים בהם כראוי.

• עליות פתאומיות בתעבורה עלולות להעמיס על השרתים, ולגרום להשבתה ולאובדן בקשות webhook.

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

• כתובות webhook לא מאובטחות עלולות להיות מנוצלות, ולאפשר לתוקפים לשלוח נתונים פגומים.

כדי לבנות פתרון חזק, כדאי לשלב webhooks עם delta queries כדי לעקוב אחר שינויים בצורה יעילה. יש גם להקים תהליכים לבדיקה וחידוש קבועים של המנויים. במשאבים שמתעדכנים לעיתים קרובות, איגוד בקשות (batching) עוזר לנהל את העומס.

הגדרה ואימות של Webhooks

הגדרת Webhooks של Microsoft Graph עבור SharePoint ו-Microsoft 365 כרוכה במספר שלבים חשובים. עליכם לרשום את ה-webhook, לטפל בבקשות אימות ולאבטח את נקודת הקצה. לכל שלב יש תפקיד קריטי בהבטחה שצינור ההתראות שלכם יפעל באופן אמין ומאובטח.

רישום Webhooks של Microsoft Graph

מתחילים ביצירת מנוי ל-webhook. תהליך זה מאפשרליישום שלכם לקבל התראות על שינויים במשאבים של Microsoft 365. בצעו את השלבים הבאים כדי לרשום את ה-webhook:

1. צרו נקודת קצה נגישה לציבור שמשתמשת ב-HTTPS. נקודת קצה זו תקבל התראות מ-Microsoft Graph.

2. שלחו בקשת POST לנקודת הקצה /subscriptions ב-Microsoft Graph.

3. בבקשת המנוי, ציינו:

   • changeType: סוגי השינויים שברצונכם לעקוב אחריהם, כגון "created", "updated" או "deleted".

   • notificationUrl: כתובת נקודת הקצה של ה-webhook שלכם.

   • resource: המשאב שברצונכם לנטר, כגון "/users" או "/drive/root".

   • expirationDateTime: התאריך והשעה שבהם המנוי צריך לפוג.

   • מאפיינים אופציונליים, כגון clientState, עוזרים לאמת את מקור ההתראות.

דוגמה לבקשת מנוי:

POST https://graph.microsoft.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "changeType": "updated",
  "clientState": "SecretClientState",
  "notificationUrl": "https://yourdomain.com/api/notifications",
  "resource": "/users",
  "expirationDateTime": "2024-05-01T00:00:00.0000000+00:00"
}

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

להלן סיכום השדות הנדרשים לרישום:

טיפול בבקשות אימות

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

• אי-החזרת ה-validationToken תגרום לשגיאת אימות. משמעות הדבר היא ש-Microsoft Graph לא יוכל לאמת את נקודת הקצה שלכם, ולא תקבלו התראות.

• כדאי להשתמש בתכונה clientState כדי לוודא שהבקשות מגיעות מהמנוי שלכם.

• החזירו תמיד את ה-validationToken בגוף התגובה כטקסט רגיל, תוך 10 שניות.

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

אבטחת HTTPS ונקודת הקצה

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

• הוסיפו IP whitelisting עבור נקודות הקצה של Microsoft Graph API.

• כללו אסימוני אימות בכותרות הבקשה.

• נטרו את השימוש ב-API כדי לזהות דפוסים חריגים או עליות חדות בפעילות.

• הגבילו את הגישה ל-Microsoft Graph ול-Outlook API. רק אנשי צוות מורשים צריכים לקבל גישה, וכדאי לאכוף אימות רב-שלבי (MFA).

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

• ביצוע ביקורות אבטחה קבועות כדי לאתר ולתקן פגיעויות.

כל קריאה חוזרת (callback) של webhook משתמשת באסימון JSON Web Token (JWT) חתום בכותרת Authentication של בקשת ה-HTTPS הנכנסת. אפשר להשתמש בטכניקות סטנדרטיות של אימות JWT לפי OpenID Connect כדי לוודא את שלמות האסימון.

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

על ידי ביצוע השלבים האלה, תגדירו צינור עיבוד אמין ומאובטח של Microsoft Graph Webhooks עבור SharePoint ו-M365. כך האפליקציה שלכם תקבל התראות במהירות ובבטחה.

עיבוד ואבטחה של התראות

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

אימות ואימות חתימה של אסימוני JWT

כל התראה מ-Microsoft Graph כוללת אסימון JSON Web Token (JWT) בכותרת Authorization. יש לאמת את האסימון לפני עיבוד כל מטען נתונים (payload). אימות JWT תקין מגן על המערכת מפני בקשות לא מורשות או שעברו שינוי.

בצעו את השלבים הבאים כדי לאמת את אסימוני JWT:

1. ודאו שהאסימון לא פג תוקף. לאסימונים יש זמן תפוגה, ויש לדחות כל אסימון שחלף זמנו.

2. ודאו שפלטפורמת הזהויות של Microsoft היא שהנפיקה את האסימון. אמתו את החתימה של האסימון כדי לוודא שלא שונה.

3. ודאו שהטענה "audience" באסימון תואמת למזהה האפליקציה שלכם. שלב זה מאשר שהאסימון נועד לאפליקציה שלכם.

4. ודאו שהמאפיין azp (authorized party) תואם לערך הצפוי עבור האפליקציה שלכם.

טיפ: השתמשו תמיד בספריות מהימנות לאימות JWT. ספריות אלה עוזרות להימנע מטעויות נפוצות ושומרות על האפליקציה מאובטחת.

כדאי גם להיזהר מ-פגיעויות אבטחה נפוצות בעבודה עם אסימוני JWT:

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

• שימוש באלגוריתם "none" בעיבוד JWT מאפשר לתוקפים לעקוף בדיקות חתימה.

• סודות חתימה חלשים מקלים על תוקפים ליצור אסימונים תקפים מזויפים.

• תוקפים עשויים להזריק פרמטרים מסוימים לכותרת ה-JOSE כדי לתפעל את האופן שבו המערכת שלכם מעבדת אסימוני JWT.

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

טיפול במטעני נתונים של התראות

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

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

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

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

• להכין את הקוד לשינויים אפשריים בגרסאות ה-API. ניתוח גמיש (flexible parsing) מבטיח שהאפליקציה תמשיך לפעול גם אם Microsoft תעדכן את פורמט מטען הנתונים.

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

יישום לוגיקת ניסיונות חוזרים והמתנה הדרגתית

בעיות רשת או השבתות זמניות עלולות לגרום לכישלון במסירת ההתראות. כדי להימנע from אובדן נתונים, יש צורך באסטרטגיית ניסיונות חוזרים והמתנה הדרגתית (backoff) איתנה. Microsoft ממליצה להשתמש ב-exponential backoff ובתורים מובנים לניהול ניסיונות חוזרים.

להלן טבלה המסכמת מנגנוני ניסיון חוזר והמתנה נפוצים:

אם לא תממשו לוגיקה נכונה של ניסיונות חוזרים והשהיה מדורגת (backoff), האפליקציה שלכם עלולה לאבד התראות או ליצור חוסר עקביות בנתונים. בקשות שנכשלו או הגבלות קצב (rate limiting) עלולות למנוע מכם לקבל עדכונים קריטיים. השהיה מעריכית (exponential backoff) עוזרת לנהל בקשות שנחנקו ומפחיתה את הסיכון להעמיס על המערכת שלכם או על Microsoft Graph Webhooks.

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

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

ניהול מנויים ומעקב אחר שינויים

אוטומציה של חידוש מנויים

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

• שלחו בקשות HTTP PATCH כדי לעדכן את תאריך התפוגה של כל מנוי.

• תזמנו את בקשות ה-PATCH לרוץ מדי יום. כך המנויים נשארים טריים ומונעים תפוגה בלתי צפויה.

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

• אם מנוי פג תוקף, צרו מיד מנוי חדש כדי להחזיר את זרימת ההתראות.

טיפ: אוטומציה של החידושים מפחיתה עבודה ידנית ומבטיחה שהמערכת שלכם תישאר מחוברת ל-Microsoft Graph.

ניטור והתראות

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

• נטרו את סטטוס המנויים ואת תאריכי התפוגה.

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

• רשמו ביומן את כל אירועי ה-webhook והשגיאות לצורך פתרון תקלות.

🛎️ ניטור יזום עוזר לתקן בעיות במהירות ושומר על האינטגרציה שלכם אמינה.

שימוש בשאילתות דלתא למעקב אחר שינויים

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

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

• הן עובדות היטב עם SharePoint ו-M365, ושולחות התראות רק כאשר משהו משתנה.

• שימוש בשאילתות דלתא חוסך רוחב פס ומשפר ביצועים.

עם זאת, לשאילתות דלתא יש כמה מגבלות:

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

על ידי אוטומציה של החידושים, ניטור הצינור שלכם ושימוש בשאילתות דלתא, אתם בונים מערכת webhook אמינה ויעילה עבור SharePoint ו-M365.

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

• הקפידו לעדכן את התיעוד ולשמור על צוותי התמיכה מעודכנים.

• תזמנו בדיקות תקופתיות של תקינות המנויים.

• השתמשו בסריקות אבטחה של צינור CI ושמרו על מסלולי ביקורת.

יישמו את שיטות העבודה המומלצות הללו כדי לוודא שהשילובים שלכם עם SharePoint ו-M365 יישארו אמינים.

שאלות נפוצות

כיצד מחדשים מנוי webhook שפג תוקפו ב-Microsoft Graph?

שלחו בקשת PATCH לנקודת הקצה /subscriptions/{id} של Microsoft Graph. עדכנו את השדה expirationDateTime. תזמנו את התהליך לרוץ מדי יום. כך המנויים נשארים פעילים ולא מפספסים התראות.

מה לעשות אם נקודת הקצה של ה-webhook נכשלת באימות?

בדקו שנקודת הקצה מחזירה את validationToken כטקסט רגיל בגוף התגובה. החזירו סטטוס 200 OK. ודאו שנקודת הקצה נגישה לציבור ושהיא משתמשת ב-HTTPS.

כיצד מאבטחים את נקודת הקצה של ה-webhook?

השתמשו ב-HTTPS בכל נקודות הקצה. אמתו אסימוני JWT בכל בקשה. הגבילו את הגישה באמצעות אימות ורשימת IP מותרים. נטרו פעילות חריגה. בצעו ביקורת קבועה של הגדרות האבטחה.

מדוע צריך להשתמש ב-delta queries עם webhooks?

Delta queries מאפשרים לעקוב רק אחר נתונים חדשים או שהשתנו. הדבר מפחית את רוחב הפס ומשפר את הביצועים. אינכם צריכים להוריד את כל הנתונים בכל פעם, וכך השילוב שלכם מהיר ויעיל יותר.

מהי הדרך הטובה ביותר לטפל בהתראות webhook שנכשלו?

יישמו לוגיקת ניסיון חוזר עם exponential backoff. עקבו אחר ניסיונות החזרה באמצעות כותרות או תורים. העבירו הודעות שנכשלו לאחר מספר ניסיונות לתור נטישה (abandon queue). חקרו את הכשלים הללו כדי למנוע אובדן נתונים.