เว็บฮุค

Webhook คือ URL ที่พาร์ทเนอร์ระบุซึ่งแพลตฟอร์ม RBM จะโพสต์ข้อความ และเหตุการณ์ URL นี้ทําหน้าที่เป็นปลายทางที่รับคําขอ HTTPS POST ซึ่งมีข้อมูล เกี่ยวกับเหตุการณ์ ซึ่งหมายความว่าระบบจะส่งข้อมูลไปยังแอปพลิเคชันของคุณอย่างปลอดภัยผ่าน HTTPS

URL ของเว็บฮุคอาจมีลักษณะดังนี้ https://[your company name].com/api/rbm-events เมื่อกำหนดค่า Webhook แล้ว คุณจะเริ่มรับข้อความและเหตุการณ์ได้

เว็บฮุคของพาร์ทเนอร์และเว็บฮุคของตัวแทน

คุณกำหนดค่าเว็บฮุคได้ที่ระดับพาร์ทเนอร์หรือระดับตัวแทน

หากคุณกําหนดค่าทั้งเว็บฮุคของพาร์ทเนอร์และเว็บฮุคของตัวแทน เว็บฮุคของตัวแทน จะมีความสําคัญเหนือกว่าตัวแทนที่เฉพาะเจาะจง ในขณะที่เว็บฮุคของพาร์ทเนอร์ จะมีผลกับตัวแทนที่ไม่มีเว็บฮุคของตนเอง

กำหนดค่าเว็บฮุคของตัวแทน

คุณจะได้รับข้อความที่ส่งไปยังตัวแทนที่เว็บฮุคของพาร์ทเนอร์ หากต้องการให้ข้อความสำหรับตัวแทนที่เฉพาะเจาะจงไปถึงเว็บฮุคอื่นแทน ให้ตั้งค่า เว็บฮุคของตัวแทน

  1. เปิดคอนโซลของนักพัฒนาซอฟต์แวร์สำหรับการสื่อสารทางธุรกิจ แล้วลงชื่อเข้าใช้ด้วยบัญชี Google ของพาร์ทเนอร์ RBM
  2. คลิกเอเจนต์
  3. คลิก Integrations
  4. สําหรับ Webhook ให้คลิกกําหนดค่า
  5. สำหรับ URL ปลายทางของเว็บฮุค ให้ป้อน URL ของเว็บฮุคโดยขึ้นต้นด้วย "https://"
  6. จดค่า clientToken คุณต้องใช้เพื่อ ยืนยันว่าข้อความที่คุณได้รับมาจาก Google

  7. กำหนดค่าเว็บฮุคให้ยอมรับคำขอ POST ที่มีพารามิเตอร์ clientToken ที่ระบุ และส่งการตอบกลับ 200 OK ที่มีค่าข้อความธรรมดาของพารามิเตอร์ secret เป็นเนื้อหาการตอบกลับ

    ตัวอย่างเช่น หากเว็บบุ๊กได้รับคำขอ POST ที่มีเนื้อหาในส่วนเนื้อหาดังนี้

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    จากนั้นเว็บฮุคควรยืนยันค่า 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 รับข้อความจากผู้ส่งได้ทุกราย คุณจึงควรยืนยันว่า Google เป็นผู้ส่งข้อความขาเข้าก่อนประมวลผลเนื้อหาข้อความ

หากต้องการยืนยันว่า Google ส่งข้อความที่คุณได้รับ ให้ทำตามขั้นตอนต่อไปนี้

  1. ดึงX-Goog-Signatureส่วนหัวของข้อความ นี่คือสำเนาของเพย์โหลดเนื้อความของข้อความที่แฮชและเข้ารหัส Base64
  2. ถอดรหัส Base64 เพย์โหลด RBM ในองค์ประกอบ message.body ของคำขอ
  3. ใช้โทเค็นไคลเอ็นต์ของ Webhook (ซึ่งคุณระบุเมื่อตั้งค่า Webhook) เป็นคีย์ สร้าง SHA512 HMAC ของไบต์ ของเพย์โหลดข้อความที่ถอดรหัส 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 จากเว็บฮุกจะถือว่าเป็นการนำส่ง ไม่สำเร็จ

นักพัฒนาแอปต้องพึงระลึกว่าการส่งข้อความในอัตราที่สูงจะ สร้างการแจ้งเตือนผ่านเว็บฮุกในอัตราที่สูง และต้องออกแบบโค้ดเพื่อ จัดการการแจ้งเตือนในอัตราที่คาดไว้ นักพัฒนาแอปควรพิจารณาสถานการณ์ที่อาจทำให้เกิดการตอบกลับที่ล้มเหลว ซึ่งรวมถึง500การตอบกลับ จากคอนเทนเนอร์บนเว็บ การหมดเวลา หรือความล้มเหลวของต้นทาง สิ่งที่ควรพิจารณา มีดังนี้

  • ตรวจสอบว่าได้กำหนดค่าการป้องกัน DDoS เพื่อรองรับอัตราการแจ้งเตือนของเว็บฮุกตามที่คาดไว้แล้ว
  • ตรวจสอบว่าทรัพยากร เช่น กลุ่มการเชื่อมต่อฐานข้อมูล ไม่หมดและ ทำให้เกิดการหมดเวลาหรือการตอบกลับ 500

นักพัฒนาแอปควรอออกแบบระบบเพื่อให้การประมวลผลเหตุการณ์ RBM เกิดขึ้นแบบไม่พร้อมกันและไม่ทำให้เว็บฮุกส่ง 200 OK กลับไม่ได้

การประมวลผล Webhook แบบอะซิงโครนัส

ไม่ควรประมวลผลเหตุการณ์ RBM ภายใน Webhook เอง ข้อผิดพลาดหรือความล่าช้าระหว่างการประมวลผลอาจส่งผลต่อรหัสการคืนค่าของเว็บฮุก

การประมวลผลเว็บบุ๊กแบบซิงโครนัส

ลักษณะการทำงานเมื่อนำส่งไม่สำเร็จ

RBM ใช้กลไกการหยุดชั่วคราวและลองใหม่เมื่อได้รับการตอบกลับอื่นที่ไม่ใช่ 200 OK จากการเรียกใช้ Webhook RBM จะเพิ่มเวลารอระหว่างการลองใหม่สูงสุด 600 วินาที ระบบจะลองส่งอีกครั้งเป็นเวลา 7 วัน หลังจากนั้นระบบจะทิ้งข้อความ

ผลกระทบของเว็บฮุกระดับตัวแทน

RBM จะจัดคิวข้อความสำหรับพาร์ทเนอร์ในคิวเดียว หากพาร์ทเนอร์ใช้ Webhook ระดับตัวแทน โปรดทราบว่าการทำงานของ Webhook รายการหนึ่งล้มเหลวจะส่งผลต่อการนำส่งไปยัง Webhook อื่นๆ ระบบจะเรียกใช้เว็บฮุคที่เป็นของเอเจนต์รายอื่น ในช่วงระยะเวลาการหยุดพักของข้อความที่ไม่สำเร็จ อย่างไรก็ตาม เมื่อข้อความที่ไม่สำเร็จเข้าคิวเพื่อลองอีกครั้ง อัตราการนำส่งโดยรวมจะลดลง และเอเจนต์อื่นๆ จะได้รับผลกระทบ

นักพัฒนาแอปควรทำความเข้าใจโมเดลนี้และเขียนโค้ดตามนั้น โดยให้ยอมรับข้อความและจัดคิวข้อความเพื่อประมวลผลให้มากที่สุดเท่าที่จะเป็นไปได้ เพื่อลดโอกาสที่จะเกิดข้อผิดพลาด

ขั้นตอนถัดไป

เมื่อกำหนดค่า Webhook แล้ว ตัวแทนจะรับข้อความจากอุปกรณ์ทดสอบได้ ส่งข้อความ เพื่อตรวจสอบการตั้งค่า

ถัดไป
Dialogflow