เว็บฮุค

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

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

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

Webhook ของพาร์ทเนอร์จะมีผลกับตัวแทนทุกรายที่คุณดูแล หากตัวแทนมีลักษณะการทำงานที่คล้ายกัน หรือหากคุณมีตัวแทนเพียงรายเดียว ให้ใช้เว็บฮุคของพาร์ทเนอร์
เว็บฮุคของตัวแทนจะมีผลกับตัวแทนแต่ละราย หากมีการใช้งานหลายตัวแทนที่มีลักษณะการทํางานแตกต่างกัน คุณสามารถตั้งค่า Webhook ที่แตกต่างกันสําหรับตัวแทนแต่ละราย

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

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

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

เปิดคอนโซลของนักพัฒนาซอฟต์แวร์สำหรับการสื่อสารทางธุรกิจ แล้วลงชื่อเข้าใช้ด้วยบัญชี Google ของพาร์ทเนอร์ RBM
คลิกตัวแทน
คลิก Integrations
สําหรับเว็บฮุค ให้คลิกกําหนดค่า
ในส่วน URL ปลายทางของเว็บฮุค ให้ป้อน URL ของเว็บฮุคที่ขึ้นต้นด้วย "https://"
จดค่า clientToken ไว้ คุณต้องใช้รหัสนี้เพื่อยืนยันว่าข้อความที่คุณได้รับมาจาก Google
กำหนดค่าเว็บฮุคให้ยอมรับคำขอ 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);
});
```
ในคอนโซลนักพัฒนาแอป ให้คลิกยืนยัน เมื่อ RBM ยืนยันเว็บฮุกแล้ว กล่องโต้ตอบจะปิดลง

ยืนยันข้อความขาเข้า

เนื่องจากเว็บฮุคสามารถรับข้อความจากผู้ส่งรายใดก็ได้ คุณจึงควรยืนยันว่า Google ได้ส่งข้อความขาเข้าก่อนประมวลผลเนื้อหาข้อความ

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

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

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

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

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

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

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

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

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

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