Webhooks - Tài liệu - Meta for Developers

Tổng quan

Webhooks cho phép các ứng dụng tích hợp tùy chỉnh đăng ký các sự kiện trong Workplace và nhận thông tin cập nhật trong thời gian thực. Khi có thay đổi trong Workplace, một yêu cầu HTTPS POST sẽ được gửi đến URL gọi lại cho mỗi ứng dụng tích hợp tùy chỉnh đã đăng ký chủ đề webhook liên quan.

Điều này giúp các ứng dụng trở nên hiệu quả hơn, vì ứng dụng sẽ biết chính xác thời điểm diễn ra thay đổi mà không cần thực hiện liên tục hay theo định kỳ các yêu cầu API Đồ thị để lấy nội dung mới nhất.

Webhooks hỗ trợ Workplace được cung cấp bằng cùng một khung dành cho Webhooks cho Facebook.

Đăng ký chủ đề webhook

Hộp thoại Chỉnh sửa tiện ích tích hợp tùy chỉnh có các tab cho mỗi chủ đề webhook dành cho các ứng dụng trên Workplace.

Tab Webhooks trong hộp thoại Chỉnh sửa tiện ích tích hợp tùy chỉnh

Để thêm gói đăng ký webhook mới trong một chủ đề nhất định, hãy cung cấp URL gọi lại và mã xác minh, sau đó chọn các trường đăng ký bạn cần cho chức năng mà ứng dụng của mình sẽ cung cấp.

Bạn chỉ có thể đăng ký một URL cho mỗi chủ đề webhook, nhưng có thể dùng cùng một URL cho nhiều chủ đề.

Xử lý yêu cầu xác minh

Khi bạn thêm gói đăng ký mới hay sửa đổi gói đăng ký hiện có, các máy chủ Facebook sẽ gửi yêu cầu GET đến URL gọi lại của bạn để xác minh tính hợp lệ của máy chủ gọi lại.

Một chuỗi truy vấn sẽ được thêm vào URL này kèm theo các thông số sau:

hub.mode - Chuỗi "subscribe" được chuyển vào thông số này
hub.challenge - Một chuỗi ngẫu nhiên
hub.verify_token - Giá trị verify_token mà bạn đã chỉ định khi tạo gói đăng ký

Khi nhận được yêu cầu HTTP GET về URL gọi lại của mình, bạn có thể dùng thông số verify_token để xác thực rằng yêu cầu đó đến từ một máy chủ của Facebook.

Bảo mật webhook

Tất cả lệnh gọi webhook đến URL gọi lại do nhà phát triển xác định đều được thực hiện thông qua HTTPS, giúp đảm bảo tính bảo mật ở cấp độ vận chuyển cho phần tải dữ liệu webhook.

Để tăng cường bảo mật, hãy thêm một tiêu đề HTTP là X-Hub-Signature-256 vào mỗi phần tải dữ liệu POST để xác minh rằng phần tải dữ liệu đến từ một máy chủ của Facebook.

Để biết thông tin đầy đủ về hành vi này, hãy tham khảo tài liệu về Khung webhook của Facebook.

Chủ đề webhook

Hoạt động trên Workplace được nhóm thành các chủ đề Mỗi chủ đề có một số trường liên kết với các sự kiện trong một chủ đề nhất định. Các ứng dụng có thể đăng ký bản cập nhật webhook trong mỗi chủ đề và các trường cụ thể trong mỗi chủ đề.

Workplace hiện cung cấp webhook cho những nhóm và chủ đề sau:

Trang

Bạn có thể xem thêm thông tin trong Tài liệu tham khảo về chủ đề trên Trang.

Trường đăng ký	Hành vi
`mention`	Được kích hoạt khi có hoạt đông nhắc đến trang (bot) tích hợp tùy chỉnh trong nhóm.
`messages`	Được kích hoạt khi có tin nhắn gửi tới trang (bot) tích hợp tùy chỉnh trong Work Chat.
`message_deliveries`	Được kích hoạt khi có hoạt động phân phối tin nhắn do trang (bot) tích hợp tùy chỉnh gửi.
`messaging_postbacks`	Được kích hoạt khi có hoạt động nhấn nút yêu cầu đăng lại trong Work Chat.
`message_reads`	Được kích hoạt khi người nhận đọc tin nhắn từ trang (bot) tích hợp tùy chỉnh.

Nhóm

Bạn có thể xem thêm thông tin trong Tài liệu tham khảo về chủ đề nhóm.

Trường đăng ký	Hành vi
`posts`	Được kích hoạt khi có hoạt động thêm, cập nhật hoặc xóa bài viết trong nhóm.
`comments`	Được kích hoạt mỗi khi có hoạt động thêm, cập nhật hoặc xóa bình luận mới khỏi bài viết trong nhóm.
`membership`	Được kích hoạt khi ai đó tham gia hoặc rời nhóm.

Người dùng

Bạn có thể xem thêm thông tin trong Tài liệu tham khảo về chủ đề người dùng.

Trường đăng ký	Hành vi
`status`	Được kích hoạt khi người dùng cập nhật trạng thái hoặc chỉnh sửa bài viết trên trang cá nhân của họ.
`events`	Được kích hoạt mỗi khi người dùng tạo, chấp nhận hoặc từ chối sự kiện.
`message_sends`	Được kích hoạt mỗi lần người dùng gửi tin nhắn trong Chat trên Workplace.

Liên kết

Bạn có thể xem thêm thông tin trong Tài liệu về bản xem trước đã xác thực.

Trường đăng ký	Hành vi
`preview`	Được kích hoạt khi Workplace cần truy xuất thông tin về một URL.
`collection`	Chỉ phù hợp với những ứng dụng có tên trong danh sách cho phép và hỗ trợ điều hướng Công cụ tạo bài viết theo cấp bậc.

Bảo mật

Bạn có thể xem thêm thông tin trong Tài liệu tham khảo về chủ đề bảo mật.

`sessions`

Các sự kiện được kích hoạt khi một người đăng nhập hoặc đăng xuất khỏi Workplace.

Sự kiện Hành vi

Sự kiện	Hành vi
`log_in`	Người dùng đã đăng nhập vào Workplace bằng mật khẩu hoặc SSO, trên www hoặc ứng dụng di động.
`log_out`	Người dùng đã đăng xuất khỏi Workplace bằng mật khẩu hoặc SSO, trên www hoặc ứng dụng di động. Không bao gồm lần buộc đăng xuất do quản trị viên khởi tạo (Xem `admin_force_log_out`)

log_in

Người dùng đã đăng nhập vào Workplace bằng mật khẩu hoặc SSO, trên www hoặc ứng dụng di động.

log_out

Người dùng đã đăng xuất khỏi Workplace bằng mật khẩu hoặc SSO, trên www hoặc ứng dụng di động.

Không bao gồm lần buộc đăng xuất do quản trị viên khởi tạo (Xem admin_force_log_out)

`passwords`

Các sự kiện được kích hoạt khi một người thay đổi mật khẩu hoặc yêu cầu đặt lại mật khẩu.

Sự kiện	Hành vi
`password_change`	Mật khẩu của người dùng được thay đổi, do hoàn tất khôi phục mật khẩu hoặc thông qua cài đặt tài khoản của họ.
`password_reset_request`	Quy trình khôi phục mật khẩu của người dùng được bắt đầu và hệ thống đã gửi mã đến địa chỉ email của người dùng.
`password_reset_wrong_code`	Người dùng đã nhập không đúng mã khôi phục đặt lại mật khẩu.
`password_reset_success`	Quy trình khôi phục mật khẩu của người dùng được hoàn tất thành công.

`admin_activity`

Các sự kiện được kích hoạt khi có hoạt động thêm hay xóa quản trị viên trong cộng đồng Workplace

Sự kiện	Hành vi
`admin_set_to_unclaimed`	Quản trị viên đã đặt trạng thái tài khoản của người dùng là chưa xác nhận trong bảng điều khiển quản trị hoặc thông qua API Quản lý tài khoản.
`admin_force_log_out`	Quản trị viên đã buộc người dùng đăng xuất trên mọi thiết bị từ Bảng điều khiển quản trị.
`admin_deactivate`	Quản trị viên đã vô hiệu hóa một tài khoản từ Bảng điều khiển quản trị hoặc thông qua API Quản lý tài khoản.
`admin_activate_account`	Quản trị viên đã kích hoạt một tài khoản từ Bảng điều khiển quản trị hoặc thông qua API Quản lý tài khoản.
`force_password_reset`	Quản trị viên đã buộc một người dùng phải đặt lại mật khẩu từ Bảng điều khiển quản trị.
`admin_create_account`	Quản trị viên đã tạo tài khoản từ Bảng điều khiển quản trị.

`two_factor`

Các sự kiện được kích hoạt khi một người bật hoặc tắt tính năng xác thực 2 yếu tố.

Sự kiện	Hành vi
`two_factor_enable`	Một người dùng đã bật tính năng xác thực 2 yếu tố từ tab Cài đặt. Sự kiện này không ghi lại khi ai đó xác nhận một số điện thoại cụ thể, nhưng cho thấy rằng tính năng này đã được bật.
`two_factor_disable`	Một người dùng đã tắt tính năng xác thực 2 yếu tố từ tab Cài đặt. Sự kiện này không ghi lại khi ai đó tắt xác thực 2 yếu tố cho một số điện thoại cụ thể, nhưng cho thấy rằng tính năng này đã bị tắt.