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

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

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

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

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

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

איך מגדירים webhook של נציג

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

פותחים את Business Communications Developer Console ונכנסים באמצעות חשבון Google של שותף RBM.
לוחצים על הנציג.
לוחצים על Integrations (שילובים).
בשביל תגובה לפעולה מאתר אחר (webhook), לוחצים על הגדרה.
בשדה webhook URL של נקודת קצה (webhook), מזינים את ה-webhook URL שמתחיל ב-'https://'.
כדאי לשים לב לערך של clientToken. הוא נדרש כדי לוודא שההודעות שאתם מקבלים מגיעות מ-Google.
צריך להגדיר את התגובה לפעולה מאתר אחר (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);
});
```
ב-Developer Console, לוחצים על אימות. כש-RBM מאמת את התגובה לפעולה מאתר אחר (webhook), תיבת הדו-שיח תיסגר.

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

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

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

חלץ את כותרת ההודעה X-Goog-Signature. זהו עותק מגובב (hash) בקידוד base64 של המטען הייעודי (payload) של גוף ההודעה.
פענוח של המטען הייעודי (payload) של RBM באמצעות Base-64 ברכיב message.body של הבקשה.
באמצעות אסימון הלקוח של ה-webhook (שהגדרתם כשהגדרתם את התגובה לפעולה מאתר אחר) כמפתח, יוצרים SHA512 HMAC של הבייטים של המטען הייעודי (payload) של ההודעה המפוענחת על בסיס 64 ומקודדים את התוצאה באמצעות base64.
משווים את הגיבוב X-Goog-Signature לגיבוב שיצרתם.
- אם הגיבובים תואמים, וידאתם ש-Google שלחה את ההודעה.
- אם הגיבובים לא תואמים, בדקו את תהליך הגיבוב לגבי הודעה שאתם יודעים שהיא טובה.
  
  אם תהליך הגיבוב (hashing) פועל כראוי וקיבלתם הודעה שלדעתכם נשלחה אליכם במרמה, תוכלו ליצור איתנו קשר.

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);

השלבים הבאים

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