Telm สามารถส่งเหตุการณ์การดูแลไปยังเซิร์ฟเวอร์ของคุณแบบเรียลไทม์ได้ คุณลงทะเบียน endpoint เลือกว่าจะรับเหตุการณ์ใด และ Telm ส่ง POST ที่ลงนามสำหรับแต่ละอัน ทุกการส่งพกลายเซ็น HMAC-SHA256ที่คุณยืนยันด้วยความลับ endpoint ของคุณ การส่งที่ล้มเหลวจะถูกลองใหม่ตามกำหนดการ endpoint ที่เข้าถึงไม่ได้อย่างถาวรจะถูกปิดใช้อัตโนมัติ
1ซองเหตุการณ์
ทุกเว็บฮุกคือ HTTP POST พร้อมเนื้อ JSON ในซองทั่วไป ซองมี id (ตัวระบุการส่งที่ไม่ซ้ำสำหรับการกำจัดข้อมูลซ้ำ) type (ชื่อเหตุการณ์) เวลา created_at, group_id ที่เหตุการณ์นั้นสังกัด และอ็อบเจกต์ data ที่รูปร่างขึ้นกับประเภทเหตุการณ์
id เป็นค่าที่กำหนดแน่นอนสำหรับเหตุการณ์จริง ดังนั้นหากเหตุการณ์เดียวกันถูกส่งสองครั้ง — เช่น หลังการลองใหม่ — คุณจะได้รับ id เดียวกันทั้งสองครั้ง ใช้เฮดเดอร์ X-Telm-Delivery (ซึ่งสะท้อน id นี้) เป็นคีย์ป้องกันการทำซ้ำเพื่อให้ตัวจัดการของคุณประมวลผลแต่ละเหตุการณ์เพียงครั้งเดียว
- ฟิลด์ของซอง คือ id, type, created_at, group_id, data
- type เป็นหนึ่งในชื่อเหตุการณ์จากรายการด้านล่าง
- data พกฟิลด์เฉพาะของเหตุการณ์
- ใช้ id (และเฮดเดอร์ X-Telm-Delivery) เพื่อกำจัดการลองใหม่ที่ซ้ำ
2รายการเหตุการณ์
คุณสมัคร endpoint ให้กับส่วนย่อยใด ๆ ของรายการ spam.detected ทำงานเมื่อเอนจินทำเครื่องหมายข้อความว่าเป็นสแปม message.suspicious ทำงานในโหมดเฝ้าดู เมื่อเอนจินจะดำเนินการแต่ให้คะแนนแบบเงาแก่ข้อความเท่านั้น เหตุการณ์สมาชิกครอบคลุมคนที่เข้า ออก และถูกลงโทษ
เหตุการณ์ ping เป็นกรณีพิเศษ คือ มันไม่ใช่ส่วนหนึ่งของรายการที่สมัครได้และถูกส่งเฉพาะเมื่อคุณกระตุ้นการส่งทดสอบสำหรับ endpoint เพื่อให้คุณยืนยันได้ว่าตัวรับและการตรวจสอบลายเซ็นของคุณทำงานครบวงจร
- spam.detected — ข้อความถูกจัดประเภทเป็นสแปม
- message.suspicious — การตรวจจับแบบเงา (โหมดเฝ้าดู)
- user.banned, user.kicked, user.muted — การดำเนินการดูแลถูกใช้
- user.joined, user.left — สมาชิกเข้าหรือออกจากกลุ่ม
- ping — เหตุการณ์ทดสอบด้วยมือ ไม่เคยถูกกระตุ้นโดยกิจกรรมจริง
3ฟิลด์ payload ต่อเหตุการณ์
สำหรับ spam.detected และ message.suspicious อ็อบเจกต์ data พก message_id, user_id, username, ข้อความ (ตัดทอนสำหรับข้อความที่ยาวมาก) การดำเนินการที่ทำ หมวดหมู่ เหตุผล ภาษาที่ตรวจพบ และคะแนนความมั่นใจ message.suspicious พกคะแนนเงาเพิ่มเติมด้วย
สำหรับเหตุการณ์สมาชิก (user.joined, user.left, user.banned, user.kicked, user.muted) อ็อบเจกต์ data พก user_id, username, first_name, message_id ที่เป็นตัวเลือก และเหตุผลเมื่อมีการใช้ เหตุการณ์เบื้องหลังหนึ่งอาจสร้างเว็บฮุกมากกว่าหนึ่ง — ข้อความสแปมที่ทำให้เกิดการแบนจะถูกส่งเป็นทั้ง spam.detected และ user.banned
- เหตุการณ์สแปม คือ message_id, user_id, username, text, action, category, reason, language, confidence (บวก score สำหรับ message.suspicious)
- เหตุการณ์สมาชิก คือ user_id, username, first_name, message_id, reason
- เหตุการณ์เดียวอาจปล่อยหลายเหตุการณ์ ให้เชื่อมโยงพวกมันด้วย user_id และ group_id
4การยืนยันลายเซ็น HMAC
แต่ละการส่งถูกลงนามเพื่อให้คุณมั่นใจได้ว่ามันมาจาก Telm จริงและไม่ถูกดัดแปลง คุณจะได้ความลับ endpoint(มันขึ้นต้นด้วย whsec_) หนึ่งครั้ง เมื่อคุณสร้าง endpoint เก็บมันและใช้มันเพื่อยืนยันทุกคำขอที่เข้ามา
ในการยืนยัน ให้นำค่าเฮดเดอร์ X-Telm-Timestamp ต่อด้วยจุด แล้วต่อด้วยเนื้อคำขอดิบตรงเป๊ะ และคำนวณ HMAC-SHA256 ของสตริงนั้นโดยใช้ความลับ endpoint ของคุณเป็นคีย์ เข้ารหัสผลลัพธ์เป็นเลขฐานสิบหกและนำหน้าด้วย v1= — มันต้องเท่ากับเฮดเดอร์ X-Telm-Signature เปรียบเทียบด้วยการเปรียบเทียบแบบเวลาคงที่ และปฏิเสธคำขอหากเวลาเก่ากว่าไม่กี่นาที (ห้านาทีเป็นจุดตัดที่ดี) เพื่อบล็อกการเล่นซ้ำ
- X-Telm-Event — ประเภทเหตุการณ์
- X-Telm-Delivery — id การส่ง (คีย์ป้องกันการทำซ้ำ)
- X-Telm-Timestamp — วินาที unix ลงนามเพื่อป้องกันการเล่นซ้ำ
- X-Telm-Signature — v1= บวกเลขฐานสิบหก HMAC-SHA256 ของเวลา จุด และเนื้อดิบ
5การส่ง การลองใหม่ และการปิดใช้อัตโนมัติ
การส่งนับว่าสำเร็จก็ต่อเมื่อ endpoint ของคุณตอบกลับด้วยสถานะ 2xx สิ่งอื่นใด — รหัสที่ไม่ใช่ 2xx การหมดเวลา หรือข้อผิดพลาดการเชื่อมต่อ — ถือเป็นความล้มเหลวและถูกลองใหม่ตามกำหนดการคงที่ คือ ทันที แล้วหลังจาก 1 นาที 5 นาที 30 นาที 2 ชั่วโมง และ 6 ชั่วโมง รวมหกครั้งกินเวลาราวแปดชั่วโมงครึ่งก่อนที่การส่งจะถูกปิดว่าล้มเหลว
หาก endpoint ยังคงล้มเหลว — อย่างน้อยยี่สิบครั้งติดต่อกันโดยไม่มีการส่งสำเร็จเป็นเวลาสามวัน — Telm จะปิดใช้มันโดยอัตโนมัติเพื่อให้มันหยุดส่งไปยัง URL ที่ตายแล้ว คุณสามารถเปิดใช้มันอีกครั้งจากแดชบอร์ดเมื่อตัวรับของคุณกลับมามีสุขภาพดี
- สำเร็จ = HTTP 2xx ตอบกลับเร็ว (ภายในราวสิบวินาที) และทำงานหนักแบบอะซิงโครนัส
- กำหนดการลองใหม่ คือ ทันที, +1 นาที, +5 นาที, +30 นาที, +2 ชั่วโมง, +6 ชั่วโมง (หกครั้ง)
- ปิดใช้อัตโนมัติหลังล้มเหลว 20 ครั้งติดต่อกันโดยไม่สำเร็จใน 72 ชั่วโมง
- การลงทะเบียนเว็บฮุกต้องใช้แพ็กเกจ Pro ขึ้นไป