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

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

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

Webhooks של שותפים ו-webhooks של נציגים

אפשר להגדיר את ה-webhook ברמת השותף או ברמת הנציג.

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

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

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

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

  1. חילוץ הכותרת X-Goog-Signature של ההודעה. זהו עותק של המטען הייעודי (payload) של גוף ההודעה, שהועבר דרך גיבוב (hash) וקידוד base64.
  2. פענוח של מטען ה-RBM ברכיב message.body בבקשה באמצעות Base-64.
  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 ממאגר האינטרנט, תפוגות זמן או כשלים ב-upstream. כדאי להביא בחשבון את הדברים הבאים:

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

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

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

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

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

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

השלבים הבאים

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