Webhooks

Tổng quan

Webhooks cho phép ứ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 theo 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 hỗ trợ Webhooks cho API Đồ thị.

Đă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.

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

Để thêm đă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 sẽ cung cấp.

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

Khi bạn thêm đăng ký mới hoặc sửa đổi đăng ký hiện có, các máy chủ của Meta 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 đăng ký

Mỗi khi nhận được yêu cầu xác minh, điểm cuối của bạn phải:

• Xác minh rằng giá trị hub.verify_token khớp với chuỗi mà bạn đã đặt trong trường Mã xác minh khi đặt cấu hình cho webhook.
• Trả về giá trị hub.challenge.

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 Meta.

Để biết thông tin đầy đủ về hành vi này, hãy tham khảo tài liệu về Khung 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.

Đăng ký webhook bằng lệnh gọi API

Các lệnh gọi API để đọc hay sửa đổi đăng ký webhook cần phải được thực hiện bằng mã ứng dụng thay vì mã tiện ích tích hợp tùy chỉnh bình thường. Mã ứng dụng có thể được tạo bằng cách ghép ID ứng dụng, ký hiệu "|" và khóa bí mật của ứng dụng.

Ví dụ:

Lấy đăng ký webhook hiện tại (sử dụng mã ứng dụng)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

Thêm đăng ký webhook mới (sử dụng mã ứng dụng)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

Khắc phục sự cố đăng ký ứng dụng/trang

Trong trường hợp không nhận được các webhook như dự kiến, bạn nên kiểm tra để đảm bảo đăng ký giữa trang và ứng dụng được thiết lập chính xác. Đăng ký này thường được thiết lập tự động, nhưng trong một số trường hợp có thể không thành công. Ví dụ: nếu việc gửi webhook không thành công trong thời gian dài, đăng ký này có thể bị gỡ. Đối với các ứng dụng bên thứ ba, điều này sẽ dẫn đến cảnh báo trong bảng điều khiển ứng dụng.

Để kiểm tra đăng ký này, các lệnh gọi API sau đây có sẵn:

Lấy đăng ký trang/ứng dụng hiện tại (bằng mã trang)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

Để tạo lại đăng ký này, các lệnh gọi API sau đây có sẵn:

Tạo lại đăng ký trang/ứng dụng hiện tại (bằng mã trang)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

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.

Nhóm

Các thông tin khác có trong Tài liệu tham khảo về chủ đề 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.

Bảo mật

Các thông tin khác có trong Tài liệu tham khảo về chủ đề bảo mật.

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

compromised_credentials

Các sự kiện được kích hoạt khi chúng tôi nghi ngờ rằng mật khẩu Workplace của một số tài khoản người dùng trong cộng đồng có thể đang gặp rủi ro.

files

Các sự kiện được kích hoạt khi có hoạt động với file trên Workplace.

groups

Các sự kiện được kích hoạt khi một người tạo hoặc tham gia Nhóm đa công ty trên Workplace.

integrations

Các sự kiện được kích hoạt khi quản trị viên tạo hoặc thay đổi các thuộc tính tích hợp.

invites

Các sự kiện được kích hoạt khi một người tham gia Workplace thông qua lời mời tự tạo.

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.

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.

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ố.

reseller_events

Các sự kiện liên quan đến bên bán lại.

Liên kết

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

Thư viện kiến thức

Bạn có thể xem thêm thông tin trong Tài liệu về API Đồ thị thuộc hạng mục Thư viện kiến thức.