เว็บฮุค

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

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

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

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

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

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

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

  1. เปิดคอนโซลของนักพัฒนาซอฟต์แวร์สำหรับการสื่อสารทางธุรกิจ แล้วลงชื่อเข้าใช้ด้วยบัญชี Google ของพาร์ทเนอร์ RCS สำหรับธุรกิจ
  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 ให้คลิกยืนยัน เมื่อ RCS สำหรับธุรกิจยืนยัน Webhook ของคุณแล้ว กล่องโต้ตอบจะปิดลง

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

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

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

  1. ดึงข้อมูลX-Goog-Signatureส่วนหัวของข้อความ นี่คือสำเนาของเพย์โหลดเนื้อความของข้อความที่แฮชและเข้ารหัส Base64
  2. ถอดรหัส Base64 ของเพย์โหลด RCS for Business ในองค์ประกอบ 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 เอง ข้อผิดพลาดหรือความล่าช้าระหว่างการประมวลผลอาจส่งผลต่อรหัสการคืนค่าของเว็บฮุก

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

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

หากเว็บฮุคแสดงผลสถานะอื่นที่ไม่ใช่ 200 OK แพลตฟอร์ม RCS for Business จะใช้กลไก Backoff และลองใหม่เพื่อส่งข้อมูลอีกครั้ง ซึ่งหมายความว่าระบบจะค่อยๆ เพิ่มความล่าช้าระหว่างการพยายามนำส่งแต่ละครั้ง จนในที่สุดจะมีความถี่สูงสุดคือลองอีกครั้งทุกๆ 10 นาที สำหรับข้อความที่รอดำเนินการแต่ละรายการ รอบการลองอีกครั้งจะดำเนินต่อไปเป็นเวลา 7 วัน หลังจากนั้นระบบจะลบข้อความอย่างถาวร

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

RCS สำหรับธุรกิจจะจัดคิวข้อความสำหรับพาร์ทเนอร์ในคิวเดียว ตัวแทนทั้งหมดภายใต้บัญชีพาร์ทเนอร์เดียวจะใช้คิวเดียวกัน ด้วยเหตุนี้ หากเว็บฮุกตัวใดตัวหนึ่งล้มเหลว ก็จะบล็อกคิวทั้งหมด ทำให้เหตุการณ์ของผู้ใช้สำหรับตัวแทนทั้งหมดไม่สามารถเข้าถึงพาร์ทเนอร์ได้

ข้อความหลายรายการที่ไม่มีการรับทราบอาจทำให้เหตุการณ์การลองใหม่เพิ่มขึ้นอย่างมาก ตัวอย่างเช่น หากตัวแทนไม่รับทราบใบตอบรับการนำส่ง 1,600 รายการ และความถี่ในการลองใหม่ถึงขีดจำกัด 10 นาที ระบบจะสร้างข้อผิดพลาดที่อาจเกิดขึ้นประมาณ 230,000 รายการต่อวัน

1,600 ข้อความ × 6 การลองใหม่ต่อชั่วโมง × 24 ชั่วโมงต่อวัน = ข้อผิดพลาดประมาณ 230,000 รายการต่อวัน

การลองใหม่จำนวนมากนี้อาจบล็อกคิว Pub/Sub ที่แชร์และทำให้เกิดความล่าช้าอย่างมากในการรับเหตุการณ์ของผู้ใช้สำหรับแคมเปญทั้งหมดของพาร์ทเนอร์

แนวทางปฏิบัติแนะนำ

โปรดทำตามแนวทางปฏิบัติแนะนำต่อไปนี้เพื่อรักษาความน่าเชื่อถือของการเข้าชมในเวอร์ชันที่ใช้งานจริงและหลีกเลี่ยงการบล็อกคิว

  • ส่งคืน 200 OK ทันที: เว็บฮุกควรได้รับข้อความ จัดเก็บไว้ในคิวภายใน และส่งคืนการตอบกลับ 200 OK ภายใน 5 วินาที
  • แยกการประมวลผล: ใช้ Worker ที่ทำงานเบื้องหลังแยกกันเพื่อประมวลผล ตรรกะของข้อความจากคิวในเครื่อง
  • ตรวจสอบ Agent ทดสอบ: ถือว่า Agent พัฒนาเป็น Agent การผลิต เนื่องจาก Agent พัฒนาอาจบล็อกคิวของพาร์ทเนอร์ที่แชร์ได้เช่นกันหากทำงานไม่สำเร็จ
  • บัญชีเฉพาะสำหรับการทดสอบ: ขอแนะนำให้ใช้บัญชีนักพัฒนาแอป 1 บัญชีสำหรับตัวแทนที่ใช้งานจริง และบัญชีนักพัฒนาแอปเฉพาะสำหรับตัวแทนทดสอบ
  • ยืนยันการเข้าชมของ Google: ใช้ Reverse DNS หรือส่วนหัว X-Goog-Signature แทนการเพิ่ม IP แบบคงที่ในรายการที่อนุญาต เนื่องจาก Google ใช้ IP แบบ Anycast แบบไดนามิก ดูข้อมูลเพิ่มเติมเกี่ยวกับการยืนยันด้วยตนเองและการระบุช่วง IP ของ Google ได้ที่เอกสารประกอบยืนยันคำขอของ Google และโดยเฉพาะอย่างยิ่งไฟล์ JSON สำหรับตัวดึงข้อมูลที่ทริกเกอร์โดยผู้ใช้และตัวดึงข้อมูลที่ทริกเกอร์โดยผู้ใช้ของ Google

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

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

ถัดไป
Dialogflow