תגובות לפעולה מאתר אחר (webhook)

‫Webhook הוא כתובת URL שמוגדרת על ידי השותף, שפלטפורמת RCS for Business מפרסמת בה הודעות ואירועים. כתובת ה-URL הזו משמשת כנקודת קצה שמקבלת בקשות HTTPS POST שמכילות נתונים על האירועים. המשמעות היא שהנתונים נשלחים לאפליקציה שלכם בצורה מאובטחת באמצעות HTTPS.

כתובת URL של webhook יכולה להיראות כך: https://[your company name].com/api/rbm-events. אחרי שמגדירים את ה-webhook, אפשר להתחיל לקבל הודעות ואירועים.

Webhooks של שותפים ו-webhooks של סוכנים

אפשר להגדיר את ה-webhook ברמת השותף או ברמת הסוכן.

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

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

הגדרת webhook של סוכן

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

  1. פותחים את Business Communications Developer Console ונכנסים באמצעות חשבון Google של השותף ב-RCS לעסקים.
  2. לוחצים על הסוכן.
  3. לוחצים על Integrations (שילובים).
  4. בקטע Webhook, לוחצים על Configure (הגדרה).
  5. בקטע Webhook endpoint URL (כתובת URL של נקודת הקצה של ה-webhook), מזינים את כתובת ה-webhook שמתחילה ב-"https://‎".
  6. חשוב לשים לב לערך של clientToken. הוא נחוץ כדי לוודא שההודעות שאתם מקבלים מגיעות מ-Google.

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

    לדוגמה, אם ה-webhook מקבל בקשת POST עם תוכן הגוף הבא

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    אז ה-webhook צריך לאשר את הערך clientToken, ואם clientToken נכון, להחזיר תגובה של 200 OK עם 1234567890 כגוף התגובה:

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. ב-Developer Console, לוחצים על אימות. כש-RCS for Business מאמת את ה-webhook, תיבת הדו-שיח נסגרת.

אימות של הודעות נכנסות

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

כדי לוודא ש-Google שלחה את ההודעה שקיבלתם, פועלים לפי השלבים הבאים:

  1. מחפשים את הכותרת X-Goog-Signature של ההודעה. זהו עותק של המטען הייעודי (payload) של גוף ההודעה, שעבר גיבוב (hashing) וקידוד Base64.
  2. מבצעים פענוח Base-64 של מטען הנתונים (payload) של RCS for Business ברכיב message.body של הבקשה.
  3. משתמשים בטוקן הלקוח של ה-webhook (שציינתם כשמגדירים את ה-webhook) כמפתח, יוצרים SHA512 HMAC של הבייטים של מטען הנתונים של ההודעה שפוענח ב-base64 ומקודדים את התוצאה ב-base64.
  4. משווים את הגיבוב X-Goog-Signature לגיבוב שיצרתם.
    • אם הגיבובים תואמים, סימן ש-Google שלחה את ההודעה.

    • אם הגיבובים לא זהים, צריך לבדוק את תהליך הגיבוב בהודעה תקינה ידועה.

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

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

טיפול בהודעות

החזרה של כל ערך אחר מלבד 200 OK מ-webhook נחשבת לכשל במסירה.

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

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

המפתחים צריכים לתכנן את המערכות שלהם כך שהעיבוד של אירועי RBM יתבצע באופן אסינכרוני, ולא ימנע מ-webhook להחזיר את הערך 200 OK.

עיבוד אסינכרוני של webhook

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

עיבוד סינכרוני של webhook

התנהגות במקרה של כשל במסירה

אם ה-webhook מחזיר סטטוס שונה מ-200 OK, פלטפורמת RCS for Business משתמשת במנגנון של השהיה וניסיון חוזר כדי לשלוח מחדש את הנתונים. המשמעות היא שהמערכת מגדילה בהדרגה את העיכוב בין כל ניסיון מסירה, עד שמגיעה לתדירות מקסימלית של ניסיון חוזר אחד כל 10 דקות לכל הודעה בהמתנה. מחזור הניסיון החוזר נמשך שבעה ימים, ולאחר מכן ההודעה נמחקת באופן סופי.

ההשלכות של webhooks ברמת הנציג

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

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

‫1,600 הודעות × 6 ניסיונות חוזרים בשעה × 24 שעות ביום = כ-230,000 שגיאות ביום

נפח הניסיונות החוזרים הזה עלול לחסום את תור Pub/Sub המשותף ולגרום לעיכובים משמעותיים בקבלת אירועי משתמשים עבור כל הקמפיינים של השותף.

שיטות מומלצות

כדי לשמור על האמינות של תנועת הנתונים בסביבת הייצור ולמנוע חסימות בתור, מומלץ לפעול לפי השיטות המומלצות הבאות:

  • החזרת 200 OK באופן מיידי: ה-webhook צריך לקבל את ההודעה, לאחסן אותה בתור מקומי ולהחזיר תגובת 200 OK תוך פחות מחמש שניות.
  • הפרדת העיבוד: שימוש בתהליכי רקע נפרדים לעיבוד לוגיקת ההודעות מהתור המקומי.
  • מעקב אחרי סוכני בדיקה: צריך להתייחס לסוכני פיתוח כמו לסוכני ייצור, כי הם יכולים לחסום את התור המשותף של השותפים אם הם נכשלים.
  • חשבונות ייעודיים לבדיקה: מומלץ להשתמש בחשבון פיתוח אחד לסוכנים פעילים ובחשבון פיתוח ייעודי לסוכני בדיקה.
  • אימות התנועה של Google: מומלץ להשתמש ב-DNS הפוך או בכותרת X-Goog-Signature במקום בשיטת הוספה לרשימת ההיתרים של כתובות IP קבועות, כי Google משתמשת בכתובות IP דינמיות מסוג anycast. למידע נוסף על אימות ידני ועל זיהוי טווחי כתובות IP של Google, אפשר לעיין במסמכי התיעוד בנושא אימות בקשות של Google, ובמיוחד בקובצי JSON בנושא אחזור נתונים שמופעל על ידי משתמשים ואחזור נתונים שמופעל על ידי משתמשים ב-Google.

השלבים הבאים

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

הבא
Dialogflow