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

Webhook הוא כתובת URL שמוגדרת על ידי השותף, שפלטפורמת RBM מפרסמת בה הודעות ואירועים. כתובת ה-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 של השותף ב-RBM.
  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, לוחצים על אימות. כש-RBM מאמת את ה-webhook, תיבת הדו-שיח נסגרת.

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

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

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

  1. מחפשים את הכותרת X-Goog-Signature של ההודעה. זהו עותק של מטען הייעודי (payload) של גוף ההודעה, שעבר גיבוב (hashing) וקידוד Base64.
  2. מפענחים את מטען ה-RBM הייעודי (payload) בקידוד Base64 ברכיב message.body של הבקשה.
  3. באמצעות טוקן הלקוח של ה-webhook (שציינתם כשמגדירים את ה-webhook), יוצרים HMAC של SHA512 של הבייטים של מטען הנתונים של ההודעה שפוענח ב-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

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

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

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

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

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

השלבים הבאים

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

הבא
Dialogflow