Webhook

RolChat gửi sự kiện đến hệ thống của bạn dưới dạng yêu cầu HTTP POST có ký. Trang này mô tả webhook của plugin; webhook do một quy tắc Automation gửi khác về số lần thử lại, thời gian chờ và việc đổi khóa bí mật, xem Webhook của Automation. Các quy tắc tương tự áp dụng theo chiều ngược lại, khi hệ thống của bạn, một plugin hoặc một nhà cung cấp gửi dữ liệu vào RolChat. Hãy xác minh mọi lần gửi theo thứ tự dưới đây trước khi xử lý.

Một lần gửi trông như thế nào

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": { … } }

Header	Ý nghĩa
`X-RolChat-Timestamp`	Số giây Unix tại thời điểm gửi. Là một phần của thông điệp được ký.
`X-RolChat-Signature`	`sha256=<hex>`. Tiền tố nêu tên thuật toán để có thể thay đổi sau này.
`X-RolChat-Nonce`	Một ULID duy nhất cho yêu cầu HTTP này. Lần thử lại nhận nonce mới.
`X-RolChat-Event-Id`	ID của chính sự kiện. Không đổi qua các lần thử lại; dùng nó để loại bỏ trùng lặp.

Lần gửi đi chỉ đến endpoint HTTPS. URL HTTP bị từ chối khi tạo đăng ký.

Chữ ký

Thông điệp được ký là dấu thời gian, một dấu chấm và body thô của yêu cầu, từng byte một:

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

Hãy ký trên các byte bạn nhận được, không phải bản sao JSON đã phân tích rồi tuần tự hóa lại. Thay đổi khoảng trắng hoặc thứ tự khóa sẽ làm hỏng chữ ký. SHA-256 là thuật toán duy nhất được chấp nhận.

Các yêu cầu do hành động HTTP của module Automation gửi đi được ký bằng hai header. X-RolChat-Signature là sha256= cộng với HMAC-SHA256 của chỉ phần body. X-RolChat-Signature-V2 là HMAC-SHA256 của <timestamp>.<body>, tức sơ đồ mô tả ở trên, với X-RolChat-Timestamp làm dấu thời gian. Hãy xác minh header V2; header chỉ ký body không bảo vệ trước yêu cầu bị phát lại. Các yêu cầu này không mang X-RolChat-Nonce và X-RolChat-Event-Id; mọi lần thử của một lần gửi mang cùng X-RolChat-Delivery-Id và số thứ tự riêng trong X-RolChat-Attempt, nên hãy bỏ qua bước kiểm tra nonce và loại trùng theo X-RolChat-Delivery-Id. Các mẫu xác minh đọc X-RolChat-Signature: với yêu cầu từ automation hãy đọc X-RolChat-Signature-V2.

Xác minh một lần gửi

Thực hiện năm bước kiểm tra này theo thứ tự. Mẫu bằng Python, Node.js, Go, Ruby và PHP có ở trang mẫu xác minh.

Độ mới. Từ chối nếu |now − X-RolChat-Timestamp| > 300 giây (400). Năm phút đủ bù độ lệch đồng hồ và khiến một yêu cầu bị đánh cắp trở nên vô dụng sau đó. Hãy đồng bộ máy chủ với NTP.
Chữ ký. Tính giá trị mong đợi và so sánh bằng phép so sánh thời gian hằng định (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Từ chối với 401 nếu không khớp. So sánh chuỗi thông thường làm lộ thông tin thời gian và không được chấp nhận.
Nonce. Lưu X-RolChat-Nonce với TTL 10 phút bằng thao tác set-if-absent nguyên tử (SET NX EX 600). Nếu đã tồn tại, từ chối với 409: đó là yêu cầu phát lại. Nếu kho lưu nonce ngừng hoạt động, hãy thất bại an toàn với 503 để RolChat thử lại; không bao giờ rơi vào trạng thái “chấp nhận”.
Chỉ đến lúc này mới phân tích body.
Loại bỏ trùng lặp theo ID sự kiện. Lần thử lại mang nonce mới nhưng cùng X-RolChat-Event-Id. Nếu bạn đã xử lý ID đó trong bảy ngày qua, hãy trả về 200 mà không xử lý lại.

Trả về 2xx ngay khi lần gửi đã được tiếp nhận an toàn; thực hiện công việc bất đồng bộ. RolChat chờ phản hồi trong 15 giây.

Khóa bí mật

Khóa bí mật của webhook gồm 64 byte ngẫu nhiên, mã hóa base64url (khoảng 86 ký tự). Nó được tạo khi tạo đăng ký hoặc plugin và chỉ hiển thị một lần.
Hãy lưu nó trong vault hoặc biến môi trường của riêng bạn; RolChat chỉ giữ một bản sao đã mã hóa.
Nên xoay vòng sau 90 ngày; sản phẩm hiển thị lời nhắc nhưng không bao giờ vô hiệu hóa đăng ký vì chưa xoay vòng.
Việc xoay vòng dùng cửa sổ chồng lấp: sau POST /api/v1/plugins/{id}/webhook-secret/rotate, cả khóa cũ và khóa mới đều xác minh được trong bảy ngày, lần gửi mới được ký bằng khóa mới, và khóa cũ bị xóa sau cửa sổ đó. Không có gì bị hỏng vào lúc bạn xoay vòng.
Nếu khóa bị lộ, POST /api/v1/plugins/{id}/webhook-secret/revoke vô hiệu hóa nó ngay lập tức, cấp khóa mới, gửi email cho các admin của tài khoản và ghi một mục kiểm toán.

Thử lại và dead letter

Phản hồi không phải 2xx hoặc lỗi mạng sẽ lên lịch thử lại:

Lần thử	Độ trễ sau lần trước
1	ngay lập tức
2	15 giây
3	1 phút
4	5 phút
5	30 phút
6	2 giờ
7	8 giờ
8	24 giờ

408, 429, 5xx và lỗi mạng được thử lại. 400, 401, 403, 404 và 410 thì không: lần gửi đi thẳng vào hàng đợi dead letter, vì thử lại một chữ ký bị từ chối hay một endpoint không tồn tại không giúp được gì. Sau tám lần thất bại, lần gửi cũng bị chuyển vào dead letter.

Dead letter được giữ 30 ngày và hiển thị trong Cài đặt → Plugin → {plugin} → Nhật ký webhook → DLQ, nơi admin có thể phát lại (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Giới hạn

Body gửi đi: mặc định 1 MB (có thể cấu hình theo plugin). Body gửi vào RolChat: 5 MB. Lớn hơn sẽ nhận 413.
Plugin có thể khai báo allowed_source_ips; RolChat áp dụng danh sách cho phép này trước khi xác minh.
Bạn có thể kiểm tra user agent RolChat-Webhook/1.0 như một bước kiểm tra hợp lý bổ sung. Đây không phải là biện pháp bảo mật.

Webhook gửi vào RolChat

Các nhà cung cấp gửi đến RolChat tại /api/v1/webhooks/{category}/{adapter} bằng cơ chế chữ ký riêng của họ (Twilio, Telnyx, Bandwidth, Meta cho WhatsApp, Stripe). Mỗi adapter xác minh chữ ký của nhà cung cấp, chuẩn hóa payload và phát lại nó trên bus sự kiện nội bộ với chữ ký RolChat. Hệ thống của bạn có thể gửi vào RolChat với cùng các header X-RolChat-* như mô tả ở trên, được ký bằng khóa bí mật của plugin sở hữu endpoint.

Webhook của Automation

Hành động Gửi yêu cầu HTTP của module Automation có quy tắc gửi riêng:

Một khóa bí mật cho mỗi tài khoản. Hiển thị hoặc đổi nó trên màn hình Automation (Owner và Admin). Việc đổi có hiệu lực ngay: không có khoảng chồng lấp, khóa cũ ngừng được xác minh ngay lập tức, nên hãy cập nhật bộ nhận trước hoặc chấp nhận một khoảng trống ngắn.
Thời gian chờ: RolChat chờ phản hồi 10 giây.
Thử lại: tối đa 6 lần thử tổng cộng. Quãng nghỉ trước lần thử thứ 2 là 30 giây, sau đó khoảng 2 phút, 8 phút, 32 phút và 2 giờ 8 phút, mỗi quãng lệch tối đa 20 %. Một quãng nghỉ không bao giờ vượt quá 6 giờ.
Những gì được thử lại: lỗi mạng, hết thời gian chờ, 5xx, 408, 425 và 429. Các phản hồi 4xx khác, địa chỉ bị chặn hoặc body quá lớn không được thử lại: lần gửi chuyển thẳng vào hàng đợi dead-letter, giống như sau lần thử thất bại cuối cùng.
Header: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Kiểm thử bộ nhận

POST /api/v1/webhooks/test-signature gửi một sự kiện có ký giả lập đến endpoint của plugin đang gọi, để bạn xác minh toàn bộ quá trình triển khai trước khi có lưu lượng thật.

Lỗi thường gặp

Xác minh trên JSON đã phân tích và mã hóa lại thay vì trên byte thô.
Dùng == để so sánh chữ ký.
Loại bỏ trùng lặp theo nonce (mỗi lần thử lại có nonce mới) thay vì theo ID sự kiện.
Đồng hồ lệch hơn năm phút.
Làm việc chậm trước khi trả lời, rồi bị quá thời gian ở 15 giây và nhận lại cùng một sự kiện.