תגובות לפעולה מאתר אחר (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 עם הפרמטר 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) => {
  // 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, לוחצים על אימות. כש-RCS לעסקים מאמת את ה-webhook, תיבת הדו-שיח נסגרת.

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

כדי לזהות את סוג הבקשה של כל הבקשות שמגיעות לתגובה לפעולה מאתר אחר (webhook), משתמשים בכותרת X-Goog-Webhook-Type.

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

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

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

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

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

  1. מחפשים את הכותרת X-Goog-Signature של ההודעה. זהו עותק של המטען הייעודי (payload) של גוף ההודעה, שעבר גיבוב (hashing) וקידוד Base64.
  2. מפענחים את מטען הנתונים (payload) של RCS for Business בקידוד Base-64 ברכיב 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 Business Messaging נכנסות לתור אחד של השותף. כל הנציגים בחשבון שותף יחיד חולקים תור יחיד. לכן, כשל ב-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