Bắt đầu

Tài liệu này giải thích cách thiết lập Webhook để thông báo cho bạn mỗi khi Người dùng ứng dụng đăng bất kỳ thay đổi nào đối với ảnh Người dùng của họ. Khi đã hiểu rõ cách thiết lập Webhook này, bạn sẽ biết cách thiết lập tất cả các Webhook.

Để thiết lập Webhook bất kỳ, bạn cần phải:

Tạo một điểm cuối trên máy chủ bảo mật để xử lý các yêu cầu HTTPS.
Đặt cấu hình sản phẩm Webhooks trong Bảng điều khiển ứng dụng của bạn.

Các bước này được giải thích chi tiết ở bên dưới.

Tạo điểm cuối

Điểm cuối của bạn phải có khả năng xử lý 2 loại yêu cầu HTTPS: Yêu cầu xác minh và Thông báo sự kiện. Vì cả hai yêu cầu này đều sử dụng HTTPS nên máy chủ của bạn phải đặt cấu hình và cài đặt chính xác một chứng chỉ TLS hoặc SSL hợp lệ. Chứng chỉ tự ký không được hỗ trợ.

Các phần bên dưới sẽ giải thích nội dung trong mỗi loại yêu cầu và cách phản hồi nội dung đó. Hoặc bạn có thể sử dụng ứng dụng mẫu của chúng tôi (đã được đặt cấu hình để xử lý các yêu cầu này).

Yêu cầu xác minh

Mỗi khi bạn đặt cấu hình sản phẩm Webhooks trong Bảng điều khiển ứng dụng, chúng tôi sẽ gửi yêu cầu GET đến URL điểm cuối của bạn. Yêu cầu xác minh sẽ bao gồm các thông số chuỗi truy vấn sau đây, được thêm vào cuối URL điểm cuối của bạn. Các yêu cầu này sẽ có dạng như sau:

Yêu cầu xác minh mẫu

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

Thông số	Giá trị mẫu	Mô tả
`hub.mode`	`subscribe`	Giá trị này sẽ luôn được đặt là `subscribe`.
`hub.challenge`	`1158201444`	Một `int` mà bạn phải chuyển lại cho chúng tôi.
`hub.verify_token`	`meatyhamhock`	Một chuỗi mà chúng tôi lấy từ trường Mã xác minh trong Bảng điều khiển ứng dụng của bạn. Bạn sẽ đặt chuỗi này khi hoàn thành các bước Cài đặt cấu hình Webhooks.

Lưu ý:PHP sẽ chuyển đổi dấu chấm (.) thành dấu gạch dưới (_) trong tên thông số.

Xác thực yêu cầu xác minh

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 sản phẩm Webhooks trong Bảng điều khiển ứng dụng (bạn chưa thiết lập chuỗi mã này).
Trả về giá trị hub.challenge.

Nếu bạn đang ở Bảng điều khiển ứng dụng và đặt cấu hình sản phẩm Webhooks (do đó, kích hoạt Yêu cầu xác minh), bảng điều khiển sẽ cho biết điểm cuối của bạn đã xác thực yêu cầu chính xác hay chưa. Nếu bạn đang sử dụng điểm cuối /app/subscriptions của API Đồ thị để đặt cấu hình sản phẩm Webhooks, API này sẽ phản hồi để cho biết có thành công hay không.

Thông báo sự kiện

Khi đặt cấu hình sản phẩm Webhooks, bạn sẽ đăng ký nhận các fields cụ thể trên loại object (ví dụ: trường photos trên đối tượng user). Mỗi khi có thay đổi đối với một trong các trường này, chúng tôi sẽ gửi yêu cầu POST đến điểm cuối của bạn kèm theo phần tải dữ liệu JSON mô tả sự thay đổi đó.

Ví dụ: nếu bạn đã đăng ký nhận trường photos của đối tượng user và một trong những Người dùng ứng dụng đã đăng Ảnh, chúng tôi sẽ gửi cho bạn một yêu cầu POST có dạng như sau:

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" }

Nội dung phần tải dữ liệu

Phần tải dữ liệu sẽ chứa một đối tượng mô tả sự thay đổi. Khi đặt cấu hình sản phẩm webhooks, bạn có thể cho biết liệu phần tải dữ liệu sẽ chỉ chứa tên của trường thông tin đã thay đổi hay sẽ bao gồm cả giá trị mới.

Chúng tôi định dạng tất cả các phần tải dữ liệu theo định dạng JSON. Vì vậy, bạn có thể phân tích cú pháp phần tải dữ liệu bằng các phương thức hoặc gói phân tích cú pháp JSON phổ biến.

Chúng tôi không lưu trữ bất kỳ dữ liệu thông báo sự kiện Webhook nào mà chúng tôi gửi cho bạn. Vì vậy, hãy nhớ chụp và lưu trữ mọi nội dung phần tải dữ liệu nào mà bạn muốn giữ.

Hầu hết các phần tải dữ liệu sẽ chứa những thuộc tính phổ biến dưới đây, nhưng nội dung và cấu trúc của từng phần tải dữ liệu sẽ khác nhau tùy thuộc vào trường đối tượng mà bạn đăng ký. Hãy xem tài liệu tham khảo của từng đối tượng để biết cần thêm những trường nào.

Thuộc tính	Mô tả	Loại
`object`	Loại đối tượng (ví dụ: `user`, `page`, v.v.)	`string`
`entry`	Một mảng chứa đối tượng mô tả các thay đổi. Nhiều thay đổi từ các đối tượng khác nhau thuộc cùng một loại có thể được nhóm với nhau.	`array`
`id`	ID của đối tượng	`string`
`changed_fields`	Một mảng chuỗi cho biết tên của các trường đã thay đổi. Chỉ được thêm nếu bạn vô hiệu hóa cài đặt Bao gồm giá trị khi đặt cấu hình sản phẩm Webhooks trong Bảng điều khiển ứng dụng của bạn.	`array`
`changes`	Một mảng chứa đối tượng mô tả các trường đã thay đổi và các giá trị mới tương ứng. Chỉ được thêm nếu bạn bật cài đặt Bao gồm giá trị khi đặt cấu hình sản phẩm Webhooks trong Bảng điều khiển ứng dụng của bạn.	`array`
`time`	Nhãn thời gian UNIX cho biết thời điểm gửi Thông báo sự kiện (chứ không phải thời điểm diễn ra thay đổi dẫn đến kích hoạt thông báo).	`int`

Xác thực phần tải dữ liệu

Chúng tôi ký mọi phần tải dữ liệu của Thông báo sự kiện bằng chữ ký SHA256 và thêm chữ ký này vào tiêu đề X-Hub-Signature-256 của yêu cầu, đứng trước là sha256=. Mặc dù bạn không phải xác thực phần tải dữ liệu này, nhưng bạn nên làm như vậy.

Cách xác thực phần tải dữ liệu:

Tạo chữ ký SHA256 bằng phần tải dữ liệu và Khóa bí mật của ứng dụng trong ứng dụng của bạn.
So sánh chữ ký của bạn với chữ ký trong tiêu đề X-Hub-Signature-256 (mọi nội dung sau sha256=). Nếu chữ ký khớp thì phần tải dữ liệu là thật.

Phản hồi Thông báo sự kiện

Điểm cuối của bạn phải phản hồi mọi Thông báo sự kiện bằng 200 OK HTTPS.

Tần suất

Thông báo sự kiện được tổng hợp và gửi hàng loạt với tối đa 1000 cập nhật. Tuy nhiên, chúng tôi không thể đảm bảo cho hành động gửi hàng loạt. Dó đó, bạn hãy nhớ điều chỉnh để máy chủ xử lý từng Webhook riêng lẻ.

Nếu không gửi được bất kỳ cập nhật nào đến máy chủ, chúng tôi sẽ thử lại ngay, sau đó thử lại thêm vài lần nữa với tần suất giảm dần trong 36 giờ tiếp theo. Máy chủ của bạn sẽ xử lý việc bỏ trùng lặp trong những trường hợp này. Các phản hồi chưa xác nhận sẽ bị bỏ qua sau 36 giờ.

Lưu ý: Tần suất gửi thông báo sự kiện trên Messenger không giống nhau. Vui lòng tham khảo tài liệu về Webhooks cho Nền tảng Messenger để biết thêm thông tin.

Đặt cấu hình sản phẩm Webhooks

Khi điểm cuối hoặc ứng dụng mẫu của bạn đã sẵn sàng, hãy sử dụng Bảng điều khiển ứng dụng của ứng dụng đó để thêm và đặt cấu hình sản phẩm Webhooks. Bạn cũng có thể thực hiện việc này theo lập trình bằng cách sử dụng điểm cuối /{app-id}/subscriptions cho mọi Webhooks, ngoại trừ Instagram.

Trong ví dụ này, chúng tôi sẽ sử dụng bảng điều khiển để đặt cấu hình Webhook. Webhook này sẽ đăng ký nhận mọi thay đổi đối với ảnh của bất kỳ Người dùng ứng dụng nào.

Trong Bảng điều khiển ứng dụng, hãy chuyển đến phần Sản phẩm > Webhooks, chọn Người dùng trong menu thả xuống rồi nhấp vào Đăng ký theo dõi đối tượng này.
Chọn đối tượng Người dùng.
Nhập URL của điểm cuối vào trường URL gọi lại rồi nhập một chuỗi vào trường Mã xác minh. Chúng tôi sẽ thêm chuỗi này vào tất cả các Yêu cầu xác minh. Nếu bạn đang sử dụng một trong các ứng dụng mẫu của chúng tôi, đây phải là chuỗi mà bạn đã dùng cho biến cấu hình TOKEN của ứng dụng.
Nếu bạn muốn phần tải dữ liệu của thông báo sự kiện chứa cả tên của trường thông tin đã thay đổi lẫn giá trị mới, hãy đặt nút chuyển Bao gồm giá trị thành Có.
Nhập URL điểm cuối và chuỗi mã xác minh.
Sau khi bạn nhấp vào Xác minh và lưu, chúng tôi sẽ gửi đến điểm cuối của bạn một Yêu cầu xác minh mà bạn phải xác thực. Nếu điểm cuối của bạn xác thực yêu cầu thành công, bạn sẽ thấy thông báo sau:
Xác thực thành công.
Bước cuối cùng là đăng ký từng trường. Hãy đăng ký nhận trường photos rồi gửi Thông báo sự kiện thử nghiệm.
Đăng ký nhận trường Ảnh trên đối tượng Người dùng.
Nếu được thiết lập chính xác, điểm cuối của bạn phải xác thực phần tải dữ liệu và thực thi bất kỳ mã nào mà bạn đã thiết lập khi xác thực thành công. Nếu đang sử dụng ứng dụng mẫu của chúng tôi, hãy tải URL của ứng dụng vào trình duyệt web của bạn. Ứng dụng này sẽ hiển thị các nội dung của phần tải dữ liệu:
Ứng dụng mẫu hiển thị phần tải dữ liệu của thông báo thử nghiệm.

Bước tiếp theo

Bây giờ, khi đã biết cách thiết lập Webhooks, bạn nên tham khảo các tài liệu khác của chúng tôi - mô tả các bước liên quan khác khi thiết lập Webhooks cho sản phẩm cụ thể: