Telm có thể đẩy các sự kiện kiểm duyệt tới máy chủ của bạn trong thời gian thực. Bạn đăng ký một endpoint, chọn các sự kiện muốn nhận, và Telm gửi một POST đã ký cho mỗi sự kiện. Mỗi lần gửi mang theo một chữ ký HMAC-SHA256 mà bạn xác minh bằng bí mật của endpoint. Các lần gửi thất bại được thử lại theo lịch trình; một endpoint không thể liên lạc được vĩnh viễn sẽ bị tự động vô hiệu hoá.
1Phong bì sự kiện
Mỗi webhook là một HTTP POST với thân JSON trong một phong bì chung. Phong bì có một id (một định danh gửi duy nhất để chống trùng lặp), một type (tên sự kiện), một dấu thời gian created_at, group_id mà sự kiện thuộc về, và một đối tượng data có hình dạng phụ thuộc vào loại sự kiện.
id có tính xác định với các sự kiện thực, nên nếu cùng một sự kiện được gửi hai lần — ví dụ sau một lần thử lại — bạn nhận được cùng một id cả hai lần. Hãy dùng header X-Telm-Delivery (phản chiếu id này) làm khoá idempotency để trình xử lý của bạn xử lý mỗi sự kiện chỉ một lần.
- Các trường phong bì: id, type, created_at, group_id, data.
- type là một trong các tên sự kiện từ danh mục bên dưới.
- data mang các trường đặc thù cho sự kiện.
- Dùng id (và header X-Telm-Delivery) để chống trùng các lần thử lại.
2Danh mục sự kiện
Bạn đăng ký một endpoint cho bất kỳ tập con nào của danh mục. spam.detected kích hoạt khi công cụ gắn cờ một tin nhắn là spam. message.suspicious kích hoạt trong chế độ giám sát, khi công cụ vốn sẽ hành động nhưng chỉ chấm điểm bóng cho tin nhắn. Các sự kiện thành viên bao quát việc người ta vào, rời đi, và bị trừng phạt.
Sự kiện ping là đặc biệt: nó không thuộc danh mục có thể đăng ký và chỉ được gửi khi bạn kích hoạt một lần gửi thử cho một endpoint, để bạn có thể xác nhận bộ nhận và kiểm tra chữ ký của mình hoạt động đầu-cuối.
- spam.detected — một tin nhắn được phân loại là spam.
- message.suspicious — một lần nhận diện bóng (chế độ giám sát).
- user.banned, user.kicked, user.muted — một hành động kiểm duyệt đã được áp dụng.
- user.joined, user.left — một thành viên vào hoặc rời nhóm.
- ping — một sự kiện thử thủ công, không bao giờ được kích hoạt bởi hoạt động thực.
3Các trường payload cho mỗi sự kiện
Với spam.detected và message.suspicious, đối tượng data mang theo message_id, user_id, username, văn bản tin nhắn (được cắt bớt với các tin nhắn rất dài), hành động đã thực hiện, một category, một reason, ngôn ngữ được nhận diện, và một điểm confidence. message.suspicious còn mang thêm điểm bóng.
Với các sự kiện thành viên (user.joined, user.left, user.banned, user.kicked, user.muted), đối tượng data mang theo user_id, username, first_name, một message_id tuỳ chọn, và một reason ở nơi áp dụng. Một sự kiện nền tảng có thể tạo ra nhiều hơn một webhook — một tin nhắn spam kích hoạt một lệnh cấm được gửi dưới dạng cả spam.detected lẫn user.banned.
- Sự kiện spam: message_id, user_id, username, text, action, category, reason, language, confidence (cộng thêm score cho message.suspicious).
- Sự kiện thành viên: user_id, username, first_name, message_id, reason.
- Một sự cố đơn lẻ có thể phát ra nhiều sự kiện; hãy tương quan chúng theo user_id và group_id.
4Xác minh chữ ký HMAC
Mỗi lần gửi được ký để bạn có thể chắc chắn nó thực sự đến từ Telm và không bị can thiệp. Bạn nhận được một bí mật endpoint (bắt đầu bằng whsec_) một lần, khi bạn tạo endpoint. Hãy lưu nó và dùng nó để xác minh mọi yêu cầu đến.
Để xác minh, lấy giá trị header X-Telm-Timestamp, thêm một dấu chấm, rồi thêm chính xác thân yêu cầu thô, và tính HMAC-SHA256 của chuỗi đó dùng bí mật endpoint của bạn làm khoá. Mã hoá kết quả sang hex và thêm tiền tố v1= vào — nó phải bằng header X-Telm-Signature. Hãy so sánh bằng phép so sánh thời-gian-hằng-số, và từ chối yêu cầu nếu dấu thời gian cũ hơn vài phút (năm phút là một mốc cắt tốt) để chặn tấn công phát lại.
- X-Telm-Event — loại sự kiện.
- X-Telm-Delivery — id của lần gửi (khoá idempotency).
- X-Telm-Timestamp — số giây unix, được ký để ngăn phát lại.
- X-Telm-Signature — v1= cộng với HMAC-SHA256 dạng hex của dấu thời gian, một dấu chấm, và thân thô.
5Gửi, thử lại và tự động vô hiệu hoá
Một lần gửi được tính là thành công chỉ khi endpoint của bạn phản hồi với mã trạng thái 2xx. Bất cứ thứ gì khác — một mã không phải 2xx, một lần hết thời gian chờ, hoặc một lỗi kết nối — đều được coi là một lần thất bại và được thử lại theo lịch cố định: ngay lập tức, rồi sau 1 phút, 5 phút, 30 phút, 2 giờ và 6 giờ, tổng cộng sáu lần thử trải dài khoảng tám tiếng rưỡi trước khi lần gửi được đóng lại là thất bại.
Nếu một endpoint liên tục thất bại — ít nhất hai mươi lần thất bại liên tiếp mà không có lần gửi nào thành công trong ba ngày — Telm tự động vô hiệu hoá nó để nó ngừng gửi tới một URL đã chết. Bạn có thể bật lại nó từ bảng điều khiển một khi bộ nhận của bạn khoẻ mạnh trở lại.
- Thành công = HTTP 2xx. Hãy phản hồi nhanh (trong khoảng mười giây) và làm các công việc nặng một cách bất đồng bộ.
- Lịch thử lại: ngay lập tức, +1p, +5p, +30p, +2g, +6g (sáu lần thử).
- Tự động vô hiệu hoá sau 20 lần thất bại liên tiếp mà không có thành công nào trong 72 giờ.
- Đăng ký webhook yêu cầu gói Pro trở lên.