เว็บฮุก

RolChat ส่งเหตุการณ์ไปยังระบบของคุณเป็นคำขอ HTTP POST ที่ลงลายมือชื่อ หน้านี้อธิบายเว็บฮุกของปลั๊กอิน ส่วนเว็บฮุกที่ส่งโดยกฎของระบบอัตโนมัติแตกต่างกันในเรื่องการลองใหม่ เวลารอ และการหมุนเวียนความลับ ดูเว็บฮุกของระบบอัตโนมัติ กฎเดียวกันใช้ในทิศทางกลับกันเมื่อระบบของคุณ ปลั๊กอิน หรือผู้ให้บริการส่งข้อมูลเข้า RolChat ตรวจสอบทุกการส่งตามลำดับด้านล่างก่อนนำไปใช้

หน้าตาของการส่ง

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…

{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }

เฮดเดอร์	ความหมาย
X-RolChat-Timestamp	วินาที Unix ขณะส่ง เป็นส่วนหนึ่งของข้อความที่ลงลายมือชื่อ
X-RolChat-Signature	sha256=<hex> คำนำหน้าระบุอัลกอริทึมเพื่อให้เปลี่ยนได้ในอนาคต
X-RolChat-Nonce	ULID ที่ไม่ซ้ำสำหรับคำขอ HTTP นี้ การลองใหม่จะได้ nonce ใหม่
X-RolChat-Event-Id	ID ของเหตุการณ์เอง คงที่ข้ามการลองใหม่ ใช้สำหรับลบรายการซ้ำ

การส่งขาออกไปยังเอนด์พอยต์ HTTPS เท่านั้น URL แบบ HTTP จะถูกปฏิเสธเมื่อสร้างการสมัครรับ

ลายมือชื่อ

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

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

ตรวจลายมือชื่อกับไบต์ที่คุณได้รับ ไม่ใช่สำเนาที่แปลง JSON แล้วแปลงกลับ การเปลี่ยนช่องว่างหรือลำดับคีย์จะทำให้ลายมือชื่อใช้ไม่ได้ SHA-256 เป็นอัลกอริทึมเดียวที่ยอมรับ

การดำเนินการอัตโนมัติ “ส่งคำขอ HTTP”

คำขอที่ส่งโดยการดำเนินการ HTTP ของโมดูล ระบบอัตโนมัติ ลงลายมือชื่อด้วยสองเฮดเดอร์ X-RolChat-Signature คือ sha256= ตามด้วย HMAC-SHA256 ของ เนื้อหาอย่างเดียว ส่วน X-RolChat-Signature-V2 คือ HMAC-SHA256 ของ <timestamp>.<body> ซึ่งเป็นรูปแบบที่อธิบายข้างต้น โดยใช้ X-RolChat-Timestamp เป็นเวลา ให้ตรวจเฮดเดอร์ V2 เฮดเดอร์ที่ใช้เนื้อหาอย่างเดียวไม่ป้องกันการเล่นคำขอซ้ำ คำขอเหล่านี้ไม่มี X-RolChat-Nonce และ X-RolChat-Event-Id ทุกความพยายามของการส่งครั้งเดียวมี X-RolChat-Delivery-Id เดียวกัน และมีหมายเลขของตัวเองใน X-RolChat-Attempt จึงข้ามการตรวจ nonce และกรองซ้ำด้วย X-RolChat-Delivery-Id ตัวอย่างการตรวจสอบอ่าน X-RolChat-Signature สำหรับคำขอจากระบบอัตโนมัติให้อ่าน X-RolChat-Signature-V2 แทน

การยืนยันการส่ง

ตรวจสอบห้าข้อนี้ตามลำดับ ตัวอย่างใน Python, Node.js, Go, Ruby และ PHP อยู่ในหน้าตัวอย่างการตรวจสอบ

1. ความสดใหม่ ปฏิเสธหาก |now − X-RolChat-Timestamp| > 300 วินาที (400) ห้านาทีเผื่อความคลาดเคลื่อนของนาฬิกาและทำให้คำขอที่ถูกดักจับไร้ค่าหลังจากนั้น ตั้งเซิร์ฟเวอร์ให้ใช้ NTP
2. ลายมือชื่อ คำนวณค่าที่คาดไว้แล้วเปรียบเทียบแบบเวลาคงที่ (hmac.compare_digest crypto.timingSafeEqual hash_equals) ปฏิเสธด้วย 401 หากไม่ตรงกัน การเปรียบเทียบสตริงธรรมดาทำให้ข้อมูลเวลารั่วไหลและยอมรับไม่ได้
3. Nonce เก็บ X-RolChat-Nonce พร้อม TTL 10 นาทีด้วยการตั้งค่าแบบอะตอมเมื่อยังไม่มี (SET NX EX 600) หากมีอยู่แล้ว ปฏิเสธด้วย 409: คำขอนั้นเป็นการส่งซ้ำ หากที่เก็บ nonce ใช้งานไม่ได้ ให้ล้มเหลวแบบปิดด้วย 503 เพื่อให้ RolChat ลองใหม่ ห้ามปล่อยผ่านเป็น “ยอมรับ”
4. แยกวิเคราะห์เนื้อหาในขั้นนี้เท่านั้น
5. ลบรายการซ้ำตาม ID เหตุการณ์ การลองใหม่มี nonce ใหม่แต่ X-RolChat-Event-Id เดิม หากคุณประมวลผล ID นั้นแล้วในเจ็ดวันที่ผ่านมา ให้ตอบ 200 โดยไม่ประมวลผลซ้ำ

ตอบ 2xx ทันทีที่รับการส่งไว้อย่างปลอดภัย แล้วทำงานแบบอะซิงโครนัส RolChat รอการตอบกลับ 15 วินาที

ซีเคร็ต

• ซีเคร็ตเว็บฮุกคือไบต์สุ่ม 64 ไบต์ เข้ารหัสแบบ base64url (ประมาณ 86 ตัวอักษร) สร้างขึ้นเมื่อสร้างการสมัครรับหรือปลั๊กอิน และแสดงเพียงครั้งเดียว
• เก็บไว้ในที่เก็บความลับหรือ environment ของคุณเอง RolChat เก็บเฉพาะสำเนาที่เข้ารหัส
• แนะนำให้หมุนเวียนหลัง 90 วัน ผลิตภัณฑ์แสดงการเตือนแต่ไม่ปิดการสมัครรับเพราะไม่ได้หมุนเวียน
• การหมุนเวียนใช้ช่วงซ้อนทับ: หลัง POST /api/v1/plugins/{id}/webhook-secret/rotate ทั้งซีเคร็ตเก่าและใหม่ใช้ตรวจสอบได้เจ็ดวัน การส่งใหม่ลงลายมือชื่อด้วยซีเคร็ตใหม่ และซีเคร็ตเก่าถูกลบหลังหมดช่วง ไม่มีอะไรเสียหายในขณะที่หมุนเวียน
• หากซีเคร็ตรั่วไหล POST /api/v1/plugins/{id}/webhook-secret/revoke จะทำให้ซีเคร็ตนั้นใช้ไม่ได้ทันที ออกซีเคร็ตใหม่ ส่งอีเมลถึงผู้ดูแลระบบของบัญชี และเขียนรายการตรวจสอบ

การลองใหม่และ dead letter

การตอบกลับที่ไม่ใช่ 2xx หรือความล้มเหลวของเครือข่ายจะนัดการลองใหม่:

ครั้งที่	หน่วงเวลาหลังครั้งก่อน
1	ทันที
2	15 วินาที
3	1 นาที
4	5 นาที
5	30 นาที
6	2 ชั่วโมง
7	8 ชั่วโมง
8	24 ชั่วโมง

408 429 5xx และข้อผิดพลาดเครือข่ายจะถูกลองใหม่ ส่วน 400 401 403 404 และ 410 จะไม่ลองใหม่: การส่งจะเข้าคิว dead letter ทันที เพราะการลองใหม่กับลายมือชื่อที่ถูกปฏิเสธหรือเอนด์พอยต์ที่ไม่มีอยู่ไม่ช่วยอะไร หลังล้มเหลวแปดครั้ง การส่งจะเข้าสู่ dead letter เช่นกัน

Dead letter ถูกเก็บ 30 วันและดูได้ใน การตั้งค่า → ปลั๊กอิน → {plugin} → บันทึกเว็บฮุก → DLQ ซึ่งผู้ดูแลระบบส่งซ้ำทีละรายการได้ (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay)

ขีดจำกัด

• เนื้อหาขาออก: ค่าเริ่มต้น 1 MB (ตั้งค่าได้ต่อปลั๊กอิน) เนื้อหาขาเข้าสู่ RolChat: 5 MB ใหญ่กว่านั้นได้ 413
• ปลั๊กอินประกาศ allowed_source_ips ได้ RolChat จะใช้รายการอนุญาตนั้นก่อนตรวจสอบ
• คุณตรวจสอบ user agent RolChat-Webhook/1.0 เพิ่มเติมได้เพื่อความมั่นใจ แต่ไม่ใช่มาตรการความปลอดภัย

เว็บฮุกขาเข้าสู่ RolChat

ผู้ให้บริการส่งข้อมูลเข้า RolChat ที่ /api/v1/webhooks/{category}/{adapter} ด้วยรูปแบบลายมือชื่อของตัวเอง (Twilio, Telnyx, Bandwidth, Meta สำหรับ WhatsApp, Stripe) อะแดปเตอร์แต่ละตัวตรวจสอบลายมือชื่อของผู้ให้บริการ ปรับเพย์โหลดให้เป็นมาตรฐาน และเผยแพร่ซ้ำบนบัสเหตุการณ์ภายในพร้อมลายมือชื่อของ RolChat ระบบของคุณเองส่งข้อมูลเข้า RolChat ได้ด้วยเฮดเดอร์ X-RolChat-* เดียวกันข้างต้น ลงลายมือชื่อด้วยซีเคร็ตของปลั๊กอินที่เป็นเจ้าของเอนด์พอยต์

เว็บฮุกของระบบอัตโนมัติ

การดำเนินการ ส่งคำขอ HTTP ของโมดูลระบบอัตโนมัติมีกฎการส่งของตัวเอง:

• หนึ่งความลับต่อบัญชี ดูหรือหมุนเวียนได้ที่หน้าระบบอัตโนมัติ (เจ้าของและผู้ดูแลระบบ) การหมุนเวียนมีผลทันที: ไม่มีช่วงซ้อนทับ ความลับเก่าจะตรวจสอบไม่ผ่านทันที จึงควรอัปเดตตัวรับของคุณก่อน หรือยอมรับช่วงขาดหายสั้นๆ
• เวลารอ: RolChat รอการตอบกลับ 10 วินาที
• การลองใหม่: รวมสูงสุด 6 ครั้ง ช่วงพักก่อนครั้งที่ 2 คือ 30 วินาที จากนั้นประมาณ 2 นาที 8 นาที 32 นาที และ 2 ชั่วโมง 8 นาที แต่ละครั้งเปลี่ยนแปลงได้ไม่เกิน 20 % ช่วงพักครั้งเดียวไม่เกิน 6 ชั่วโมง
• สิ่งที่ลองใหม่: ข้อผิดพลาดของเครือข่าย การหมดเวลา 5xx 408 425 และ 429 คำตอบ 4xx อื่น ที่อยู่ที่ถูกบล็อก หรือเนื้อหาที่ใหญ่เกินไปจะไม่ลองใหม่: การส่งนั้นเข้าคิวข้อความที่ส่งไม่สำเร็จ (dead-letter) ทันที เช่นเดียวกับหลังความพยายามครั้งสุดท้ายที่ล้มเหลว
• เฮดเดอร์: X-RolChat-Signature X-RolChat-Signature-V2 X-RolChat-Timestamp X-RolChat-Delivery-Id X-RolChat-Attempt

ทดสอบตัวรับของคุณ

POST /api/v1/webhooks/test-signature ส่งเหตุการณ์จำลองที่ลงลายมือชื่อไปยังเอนด์พอยต์ของปลั๊กอินที่เรียก เพื่อให้คุณตรวจสอบการทำงานตั้งแต่ต้นจนจบก่อนที่ทราฟฟิกจริงจะเข้ามา

ข้อผิดพลาดที่พบบ่อย

• ตรวจสอบกับ JSON ที่แยกวิเคราะห์และเข้ารหัสใหม่ แทนไบต์ดิบ
• ใช้ == เปรียบเทียบลายมือชื่อ
• ลบรายการซ้ำตาม nonce (ทุกการลองใหม่มี nonce ใหม่) แทนการใช้ ID เหตุการณ์
• นาฬิกาคลาดเคลื่อนเกินห้านาที
• ทำงานที่ช้าก่อนตอบกลับ แล้วหมดเวลาที่ 15 วินาทีและได้รับเหตุการณ์เดิมอีกครั้ง