เว็บฮุก — เหตุการณ์การกลั่นกรองแบบเรียลไทม์ในระบบของคุณ

1เว็บฮุกทำอะไร

แทนที่จะ poll API คุณลงทะเบียน URL แล้ว Telm ส่ง HTTP POST ที่ลงนามไปยังมันเมื่อใดก็ตามที่มีบางอย่างเกิดขึ้นในกลุ่มของคุณ นั่นคือวิธีที่คุณนำเหตุการณ์การกลั่นกรองเข้าสู่ระบบของคุณเอง — แดชบอร์ด คลังข้อมูล ช่องแจ้งเตือน — แบบเรียลไทม์

คุณจัดการเอนด์พอยต์เว็บฮุกผ่าน API: ลงทะเบียน URL เลือกเหตุการณ์ที่จะสมัคร จำกัดไว้เฉพาะบางกลุ่มได้ ส่ง ping ทดสอบ และอ่านบันทึกการส่งล่าสุด

2ทำไมการพุชจึงดีกว่าการ poll

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

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

• เรียลไทม์: คุณรู้เกี่ยวกับเหตุการณ์ขณะที่มันเกิดขึ้น ไม่ใช่ในการ poll ครั้งถัดไป
• มีประสิทธิภาพ: ไม่มีการอ่านซ้ำ ๆ ที่กินโควตารายวันของคุณ
• ครบถ้วน: การส่งจะถูกลองใหม่ ดังนั้นการขัดข้องสั้น ๆ ฝั่งคุณไม่ทำให้สูญเสียเหตุการณ์

3เหตุการณ์ที่คุณสมัครได้

มีเหตุการณ์ที่สมัครได้เจ็ดประเภท ครอบคลุมการตัดสินสแปม การลงโทษ และการเปลี่ยนแปลงสมาชิก ข้อความที่ถูกกลั่นกรองหนึ่งข้อความอาจสร้างเหตุการณ์มากกว่าหนึ่งอย่าง — ข้อความสแปมที่จบด้วยการแบนจะปล่อยทั้ง spam.detected และ user.banned

• spam.detected — เอนจินทำเครื่องหมายข้อความว่าเป็นสแปม
• message.suspicious — การตรวจจับแบบเงา (โหมดเฝ้าติดตาม) พร้อมคะแนน
• user.banned — สมาชิกถูกแบน
• user.kicked — สมาชิกถูกลบออก
• user.muted — สมาชิกถูกปิดเสียง
• user.joined — สมาชิกเข้ากลุ่ม
• user.left — สมาชิกออกจากกลุ่ม

4ซองเพย์โหลด

การส่งแต่ละครั้งเป็นซอง JSON ที่มีชุดฟิลด์ระดับบนสุดที่เล็กและเสถียร และออบเจ็กต์ data เฉพาะเหตุการณ์อยู่ข้างใน คุณสามารถกำหนดเส้นทางตาม type และเวลาโดยไม่ต้องแยกวิเคราะห์รายละเอียดจนกว่าคุณจะต้องการ

• id — delivery id ที่ไม่ซ้ำ การส่งซ้ำของเหตุการณ์เดียวกันใช้ id เดิม ซึ่งเป็นวิธีที่คุณกำจัดข้อมูลซ้ำ
• type — ประเภทเหตุการณ์ หนึ่งในเจ็ดข้างต้น
• created_at — เมื่อเหตุการณ์เกิดขึ้น ในรูปแบบ RFC3339 UTC
• group_id — กลุ่มที่เหตุการณ์เป็นของ (เมื่อเกี่ยวข้อง)
• data — ออบเจ็กต์เฉพาะเหตุการณ์: รายละเอียดข้อความและการตัดสินสำหรับเหตุการณ์สแปม รายละเอียดสมาชิกสำหรับเหตุการณ์สมาชิก

5การตรวจสอบว่าการส่งมาจาก Telm จริง

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

ลายเซ็นคือ HMAC-SHA256 ของ timestamp และเนื้อความคำขอดิบ โดยใช้คีย์เป็นความลับการลงนามเอนด์พอยต์ของคุณ ในการตรวจสอบ ให้คำนวณ HMAC ใหม่เหนือเฮดเดอร์ timestamp และไบต์ที่คุณได้รับพอดี แล้วเปรียบเทียบกับเฮดเดอร์ลายเซ็น

• X-Telm-Signature — ลายเซ็น จัดรูปแบบเป็น v1 ตามด้วย HMAC-SHA256 แบบ hex ของ timestamp ที่ต่อกับเนื้อความ
• X-Telm-Timestamp — timestamp หน่วยวินาที unix ที่ถูกลงนาม เพื่อให้คุณปฏิเสธการส่งที่เก่าหรือถูกส่งซ้ำได้
• X-Telm-Event — ประเภทเหตุการณ์ และ X-Telm-Delivery — delivery id สำหรับการกำจัดข้อมูลซ้ำ
• ความลับการลงนามจะแสดงครั้งเดียวเมื่อคุณสร้างเอนด์พอยต์และเริ่มด้วย whsec_ จัดเก็บอย่างปลอดภัย มันเป็นสิ่งเดียวที่พิสูจน์ว่าการส่งนั้นแท้จริง

6การส่งที่เชื่อถือได้และกำจัดข้อมูลซ้ำ

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

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

• ตอบสนองอย่างรวดเร็วด้วยสถานะ 2xx ทำงานหนักแบบอะซิงโครนัสหลังจากตอบรับ
• กำจัดข้อมูลซ้ำที่ delivery id — ไม่ใช่ที่เนื้อหาเพย์โหลด
• เอนด์พอยต์ที่ล้มเหลวประมาณยี่สิบครั้งติดต่อกันโดยไม่สำเร็จภายในหน้าต่าง 72 ชั่วโมงจะถูกปิดใช้งานอัตโนมัติ เปิดใช้งานใหม่เมื่อเซิร์ฟเวอร์ของคุณสมบูรณ์ดี

7การจัดการเอนด์พอยต์และการอ่านบันทึก

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

เอนด์พอยต์แต่ละอันเก็บบันทึกการส่งที่คุณสามารถอ่านย้อนหลังเพื่อดูว่าอะไรถูกส่ง เมื่อไร และสำเร็จหรือไม่ — มีประโยชน์สำหรับการดีบักผู้รับโดยไม่ต้องรอเหตุการณ์สดครั้งถัดไป

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

8แนวปฏิบัติที่ดีและข้อผิดพลาดที่พบบ่อย

ผู้รับที่แข็งแกร่งปฏิบัติตามกฎไม่กี่ข้อที่ป้องกันปัญหาที่พบบ่อยที่สุด

• ตรวจสอบลายเซ็นเหนือไบต์เนื้อความดิบ — การแยกวิเคราะห์เป็น JSON ก่อนแล้วซีเรียลไลซ์ใหม่อาจเปลี่ยนไบต์และทำให้การตรวจล้มเหลว
• ส่งกลับ 2xx อย่างรวดเร็วและประมวลผลภายหลัง ตัวจัดการที่ช้าทำให้เกิดการหมดเวลาและการลองใหม่ที่ไม่จำเป็น
• ทำให้การจัดการเป็นแบบ idempotent เพื่อไม่ให้เหตุการณ์ที่ส่งซ้ำนับซ้ำ
• ใช้ HTTPS บน URL ที่เข้าถึงได้แบบสาธารณะ Telm บล็อกที่อยู่ภายในและส่วนตัวและไม่ตาม redirect
• เก็บความลับ whsec_ ให้พ้นจากบันทึกและโค้ดไคลเอนต์