תגובות לפעולה מאתר אחר (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. פותחים את RCS for Business Developer Console ונכנסים באמצעות חשבון Google של שותף RCS for Business.
  2. לוחצים על הסוכן.
  3. לוחצים על Integrations (שילובים).

  4. בקטע Webhook, לוחצים על הגדרה.

    1. בקטע Webhook endpoint (נקודת קצה של webhook), מזינים את כתובת ה-URL של ה-webhook שמתחילה ב-"https://‎".
    2. בשדה Client token (אסימון לקוח), מציינים את הערך clientToken. הוא נחוץ כדי לוודא שההודעות שאתם מקבלים מגיעות מ-Google.

  5. מגדירים את ה-webhook לקבלת בקשות POST עם מטען ייעודי (payload) בפורמט JSON שכולל את הפרמטרים clientToken ו-secret.

    {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
}

    כדי לאמת את הבקשה, נקודת הקצה צריכה להחזיר קוד סטטוס HTTP 200 OK עם ערך המחרוזת הגולמי של הפרמטר secret בגוף התגובה.

    דוגמה להגדרת webhook

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

      {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
  }

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

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

  // Example endpoint
  app.post("/rbm-webhook", (req, res) => {
    // Use the X-Goog-Webhook-Type header to route requests
    const webhookType = req.header('X-Goog-Webhook-Type');

    if (webhookType === 'verification') {
      const msg = req.body;
      if (msg.clientToken === myClientToken) {
          res.status(200).send(msg.secret);
          return;
      }
    }
    res.send(400);
    // Handle other webhook types
  });

  6. ב-Developer Console, לוחצים על אימות. אחרי שלוחצים על אימות, Google שולחת בקשת POST ל-webhook עם הפרמטרים clientToken ו-secret בגוף הבקשה. אחרי ש-RCS for Business מאמת את ה-webhook, תיבת הדו-שיח נסגרת.

זיהוי סוגי בקשות

כדי לזהות את סוג הבקשה שמגיעה אל ה-webhook, צריך להשתמש בכותרת X-Goog-Webhook-Type.

הכותרת יכולה לקבל את הערכים הבאים:

  • ‫verification: משמש לתהליך האימות הראשוני של נקודת הקצה.
  • ‫message_callback: משמש לאירועים שקשורים להודעות, כמו הקלדה או התראות על מסירה והודעות נכנסות ממשתמשים.
  • ‫agent_callback: משמש לאירועים אדמיניסטרטיביים שספציפיים לסוכן, כמו שינויים במצב ההפעלה של הסוכן.

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

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

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

  1. מחפשים את הכותרת X-Goog-Signature של ההודעה. זהו עותק של המטען הייעודי (payload) של גוף ההודעה, שעבר גיבוב (hashing) וקידוד Base64.
  2. מבצעים פענוח Base-64 של מטען הייעודי (payload) של RCS for Business ברכיב message.body של הבקשה.
  3. משתמשים בטוקן הלקוח של ה-webhook (שציינתם כשמגדירים את ה-webhook) כמפתח, יוצרים HMAC מסוג SHA512 של בייט של מטען הייעודי (payload) של ההודעה שפוענח ב-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
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

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

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

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

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

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

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

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

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

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

אם ה-webhook מחזיר סטטוס שאינו 200 OK, פלטפורמת RCS לעסקים משתמשת במנגנון של השהיה וניסיון חוזר כדי לשלוח מחדש את הנתונים. המשמעות היא שהמערכת מגדילה בהדרגה את העיכוב בין כל ניסיון מסירה, עד שמגיעה לתדירות מקסימלית של ניסיון חוזר אחד בכל 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