Webhook — các sự kiện kiểm duyệt thời gian thực trong hệ thống của bạn

1Webhook làm gì

Thay vì thăm dò API, bạn đăng ký một URL và Telm gửi một HTTP POST được ký đến nó bất cứ khi nào có điều gì đó xảy ra trong nhóm của bạn. Đó là cách bạn đưa các sự kiện kiểm duyệt vào hệ thống của riêng mình — một bảng điều khiển, một kho dữ liệu, một kênh cảnh báo — theo thời gian thực.

Bạn quản lý các endpoint webhook thông qua API: đăng ký một URL, chọn đăng ký sự kiện nào, tùy chọn giới hạn chúng cho các nhóm cụ thể, gửi một ping thử nghiệm, và đọc nhật ký giao gần đây.

2Vì sao đẩy tốt hơn thăm dò

Bạn có thể gọi endpoint nhật ký theo một bộ hẹn giờ để tìm các sự kiện mới, nhưng điều đó thêm độ trễ, tiêu tốn hạn mức, và có thể bỏ lỡ đúng khoảnh khắc điều gì đó xảy ra. Webhook đảo ngược mô hình: Telm báo cho bạn ngay khi một sự kiện kích hoạt, nên các hệ thống của bạn phản ứng trong vài giây.

Các cách dùng điển hình bao gồm phản chiếu các lệnh cấm vào các công cụ quản trị của riêng bạn, cảnh báo một kênh của nhóm khi một cuộc tấn công được phát hiện, truyền các phát hiện vào phân tích, hoặc kích hoạt một quy trình khi một thành viên tham gia hoặc rời đi.

• Thời gian thực: bạn biết về một sự kiện khi nó xảy ra, không phải ở lần thăm dò tiếp theo.
• Hiệu quả: không có các lượt đọc lặp lại ngốn vào hạn mức hằng ngày của bạn.
• Hoàn chỉnh: các lần giao được thử lại, nên một sự cố ngắn ở phía bạn không làm mất sự kiện.

3Các sự kiện bạn có thể đăng ký

Có bảy loại sự kiện có thể đăng ký, bao gồm các phán quyết spam, hình phạt và thay đổi thành viên. Một tin nhắn được kiểm duyệt đơn lẻ có thể tạo ra hơn một sự kiện — một tin nhắn spam kết thúc bằng một lệnh cấm phát ra cả spam.detected và user.banned.

• spam.detected — công cụ đã gắn cờ một tin nhắn là spam.
• message.suspicious — một phát hiện bóng (chế độ giám sát) kèm một điểm số.
• user.banned — một thành viên đã bị cấm.
• user.kicked — một thành viên đã bị gỡ bỏ.
• user.muted — một thành viên đã bị tắt tiếng.
• user.joined — một thành viên đã tham gia nhóm.
• user.left — một thành viên đã rời nhóm.

4Phong bì payload

Mỗi lần giao là một phong bì JSON với một tập nhỏ, ổn định các trường cấp cao nhất và một đối tượng data đặc thù cho sự kiện bên trong. Bạn có thể định tuyến theo type và thời gian mà không cần phân tích các chi tiết cho đến khi bạn cần chúng.

• id — một delivery id duy nhất; các lần giao lại của cùng một sự kiện tái sử dụng cùng id, đó là cách bạn khử trùng lặp.
• type — loại sự kiện, một trong bảy loại ở trên.
• created_at — khi sự kiện kích hoạt, ở RFC3339 UTC.
• group_id — nhóm mà sự kiện thuộc về (khi áp dụng).
• data — một đối tượng đặc thù cho sự kiện: các chi tiết tin nhắn và phán quyết cho các sự kiện spam, các chi tiết thành viên cho các sự kiện thành viên.

5Xác minh các lần giao thực sự đến từ Telm

Mỗi lần giao được ký để máy chủ của bạn có thể xác nhận yêu cầu thực sự đến từ Telm và không bị can thiệp khi truyền. Hãy xác thực chữ ký trước khi bạn tin payload, và từ chối bất cứ thứ gì không khớp.

Chữ ký là một HMAC-SHA256 của dấu thời gian và phần thân yêu cầu thô, được khóa bằng bí mật ký của endpoint của bạn. Để xác minh, tính lại HMAC trên header dấu thời gian và đúng các byte bạn đã nhận, và so sánh nó với header chữ ký.

• X-Telm-Signature — chữ ký, được định dạng là v1 theo sau bởi HMAC-SHA256 dạng hex của dấu thời gian nối với phần thân.
• X-Telm-Timestamp — dấu thời gian tính bằng giây-unix được ký, nên bạn có thể từ chối các lần giao cũ hoặc bị phát lại.
• X-Telm-Event — loại sự kiện, và X-Telm-Delivery — delivery id để khử trùng lặp.
• Bí mật ký chỉ được hiển thị một lần khi bạn tạo endpoint và bắt đầu bằng whsec_. Lưu nó an toàn; nó là thứ duy nhất chứng minh một lần giao là chính hãng.

6Giao hàng đáng tin cậy, đã khử trùng lặp

Giao hàng là ít-nhất-một-lần: Telm đảm bảo một sự kiện đến được với bạn, nghĩa là cùng một sự kiện đôi khi có thể đến hai lần. Vì mỗi lần giao lại tái sử dụng cùng một delivery id, bạn khử trùng lặp bằng cách lưu các id bạn đã xử lý và bỏ qua các lần lặp.

Nếu endpoint của bạn không tiếp cận được hoặc trả về một lỗi, lần giao được thử lại theo một lịch cố định — khoảng sau một phút, năm phút, ba mươi phút, hai giờ và sáu giờ, lên tới sáu lần thử trong khoảng tám tiếng rưỡi. Một endpoint cứ liên tục thất bại được tự động vô hiệu hóa để bảo vệ cả hai bên, và chủ sở hữu được thông báo.

• Phản hồi nhanh với một trạng thái 2xx; làm công việc nặng một cách bất đồng bộ sau khi xác nhận.
• Khử trùng lặp theo delivery id — không bao giờ theo nội dung payload.
• Một endpoint thất bại khoảng hai mươi lần liên tiếp mà không thành công trong một cửa sổ 72 giờ sẽ bị tự động vô hiệu hóa; bật lại nó khi máy chủ của bạn khỏe mạnh.

7Quản lý các endpoint và đọc nhật ký

Bạn đăng ký, chỉnh sửa và gỡ bỏ các endpoint webhook thông qua API. Khi bạn tạo một endpoint, bạn nhận được bí mật ký đúng một lần, chọn các sự kiện để đăng ký, và tùy chọn giới hạn phạm vi nó cho các nhóm cụ thể. Một lệnh gọi thử nghiệm gửi một ping được ký để bạn có thể xác nhận việc xác minh của mình hoạt động trước khi lưu lượng thực bắt đầu.

Mỗi endpoint giữ một nhật ký giao mà bạn có thể đọc lại để xem những gì đã được gửi, khi nào, và liệu nó có thành công không — tiện lợi để gỡ lỗi một bộ nhận mà không cần chờ sự kiện trực tiếp tiếp theo.

• Tạo một endpoint và sao chép bí mật whsec_ ngay lập tức.
• Gửi một ping thử nghiệm để xác thực việc kiểm tra chữ ký của bạn từ đầu đến cuối.
• Giới hạn phạm vi một endpoint cho một nhóm hoặc để nó mở cho tất cả các nhóm bạn quản trị.
• Đọc nhật ký giao để kiểm tra các lần thử gần đây và kết quả của chúng.

8Thực hành tốt nhất và những sai lầm thường gặp

Một bộ nhận vững chắc tuân theo một vài quy tắc ngăn ngừa những vấn đề thường gặp nhất.

• Xác minh chữ ký trên các byte phần thân thô — phân tích sang JSON trước rồi tuần tự hóa lại có thể thay đổi các byte và làm hỏng việc kiểm tra.
• Trả về 2xx nhanh và xử lý sau; một handler chậm gây ra timeout và các lần thử lại không cần thiết.
• Làm cho việc xử lý có tính idempotent để một sự kiện được giao lại không bị đếm hai lần.
• Dùng HTTPS trên một URL tiếp cận công khai được; Telm chặn các địa chỉ nội bộ và riêng tư và không theo các chuyển hướng.
• Giữ bí mật whsec_ ngoài các log và mã phía client.