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.

Create an Endpoint

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

The sections below explain what will be in each type of request and how to respond to them. Alternatively, you can use our sample app which is already configured to process these requests.

Verification Requests

Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

Sample Verification Request

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

Parameter	Sample Value	Description
`hub.mode`	`subscribe`	This value will always be set to `subscribe`.
`hub.challenge`	`1158201444`	An `int` you must pass back to us.
`hub.verify_token`	`meatyhamhock`	A string that that we grab from the Verify Token field in your app's App Dashboard. You will set this string when you complete the Webhooks configuration settings steps.

Note: PHP converts periods (.) to underscores (_) in parameter names.

Validating Verification Requests

Whenever your endpoint receives a verification request, it must:

Verify that the hub.verify_token value matches the string you set in the Verify Token field when you configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).
Respond with the hub.challenge value.

If you are in your App Dashboard and configuring your Webhooks product (and thus, triggering a Verification Request), the dashboard will indicate if your endpoint validated the request correctly. If you are using the Graph API's /app/subscriptions endpoint to configure the Webhooks product, the API will indicate success or failure with a response.

Event Notifications

When you configure your Webhooks product, you will subscribe to specific fields on an object type (e.g., the photos field on the user object). Whenever there's a change to one of these fields, we will send your endpoint a POST request with a JSON payload describing the change.

For example, if you subscribed to the user object's photos field and one of your app's Users posted a Photo, we would send you a POST request that would look something like this:

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"
}

Payload Contents

Payloads will contain an object describing the change. When you configure the webhooks product, you can indicate if payloads should only contain the names of changed fields, or if payloads should include the new values as well.

We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.

We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.

Most payloads will contain the following common properties, but the contents and structure of each payload varies depending on the object fields you are subscribed to. Refer to each object's reference document to see which fields will be included.

Property	Description	Type
`object`	The object's type (e.g., `user`, `page`, etc.)	`string`
`entry`	An array containing an object describing the changes. Multiple changes from different objects that are of the same type may be batched together.	`array`
`id`	The object's ID	`string`
`changed_fields`	An array of strings indicating the names of the fields that have been changed. Only included if you disable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`changes`	An array containing an object describing the changed fields and their new values. Only included if you enable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`time`	A UNIX timestamp indicating when the Event Notification was sent (not when the change that triggered the notification occurred).	`int`

Validating Payloads

We sign all Event Notification payloads with a SHA256 signature and include the signature in the request's X-Hub-Signature-256 header, preceded with sha256=. You don't have to validate the payload, but you should.

To validate the payload:

Generate a SHA256 signature using the payload and your app's App Secret.
Compare your signature to the signature in the X-Hub-Signature-256 header (everything after sha256=). If the signatures match, the payload is genuine.

Responding to Event Notifications

Your endpoint should respond to all Event Notifications with 200 OK HTTPS.

Frequency

Event Notifications are aggregated and sent in a batch with a maximum of 1000 updates. However batching cannot be guaranteed so be sure to adjust your servers to handle each Webhook individually.

If any update sent to your server fails, we will retry immediately, then try a few more times with decreasing frequency over the next 36 hours. Your server should handle deduplication in these cases. Unacknowledged responses will be dropped after 36 hours.

Note: The frequency with which Messenger event notifications are sent is different. Please refer to the Messenger Platform Webhooks documentation for more information.

Đặ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 trên ứ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 Webhook, 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 những trường đã 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 trên sẽ hiển thị 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.

mTLS cho Webhooks

Mutual TLS (mTLS) là một phương thức để xác thực lẫn nhau.

mTLS đảm bảo rằng các bên ở mỗi đầu của kết nối mạng đều đúng như những gì họ tuyên bố bằng cách xác minh rằng cả hai bên đều có khóa riêng tư chính xác. Các chứng chỉ TLS tương ứng sẽ cung cấp thêm thông tin xác minh.

Cách đặt cấu hình mTLS

Khi bạn bật mTLS trên gói đăng ký cho Tài khoản WhatsApp Business, Meta sẽ cung cấp một chứng chỉ máy khách cùng với chứng chỉ ký trung gian. Cả hai chứng chỉ này được dùng để tạo phương thức giao tiếp qua TLS khi gửi các yêu cầu Webhooks đến máy chủ của bạn. Sau đó, máy chủ của bạn có thể xác minh danh tính của người gửi những yêu cầu này bằng chuỗi tin cậy và tên chung (CN).

Chứng chỉ máy khách nêu trên được ký bởi chứng chỉ CA trung gian (DigiCert SHA2 High Assurance Server CA), sau đó là chứng chỉ CA gốc (DigiCert High Assurance EV Root CA). Lưu ý rằng chứng chỉ trung gian cũng ký chứng chỉ cho graph.facebook.com:

Xác minh chứng chỉ máy khách

Sau khi thiết lập HTTPS để nhận yêu cầu Webhook, hãy hoàn tất các bước sau để xác minh chứng chỉ máy khách và tên chung client.webhooks.fbclientcerts.com của chứng chỉ đó:

Cài đặt chứng chỉ gốc
Xác minh chứng chỉ máy khách dựa trên chứng chỉ gốc
Xác minh tên chung (client.webhooks.fbclientcerts.com) của chứng chỉ máy khách

Lưu ý: Máy chủ nhận Webhooks phải sử dụng HTTPS. Chúng tôi luôn xác minh chứng chỉ từ máy chủ HTTPS của bạn để đảm bảo tính bảo mật.

Ví dụ

Tùy thuộc vào cách thiết lập máy chủ của bạn, thông tin chi tiết về các bước trên đây có thể khác nhau. Chúng tôi sẽ cung cấp 2 ví dụ minh họa: một cho Nginx và một cho Trình cân bằng tải ứng dụng AWS (ALB).

Nginx

Tải chứng chỉ gốc (DigiCert High Assurance EV Root CA) từ DigiCert xuống máy chủ của bạn (ví dụ: /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem)

Bật mTLS bằng lệnh Nginx (ảnh chụp màn hình mẫu)

ssl_verify_client       on;
ssl_client_certificate  /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem;
ssl_verify_depth        3;

Xác minh CN trong biến nhúng $ssl_client_s_dn của Nginx để đảm bảo rằng CN đó bằng "client.webhooks.fbclientcerts.com" (ảnh chụp màn hình mẫu)
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

Trình cân bằng tải ứng dụng AWS (ALB)

Tải chứng chỉ trung gian (DigiCert SHA2 High Assurance Server CA) từ DigiCert xuống một bộ chứa S3. Chứng chỉ gốc không được AWS chấp nhận vì chứng chỉ này được ký bằng thuật toán SHA1withRSA. Trong khi đó, chứng chỉ trung gian được ký bằng thuật toán SHA256withRSA nên được AWS chấp nhận.
Đặt cấu hình trình nghe HTTPS trên ALB để bật mTLS, sử dụng kho lưu trữ tin cậy chứa chứng chỉ trong bộ chứa S3 (ảnh chụp màn hình mẫu).
Trong mã ứng dụng của bạn, hãy trích xuất CN từ tiêu đề HTTP "X-Amzn-Mtls-Clientcert-Subject" và xác minh để đảm bảo rằng CN đó bằng “client.webhooks.fbclientcerts.com”.

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ể: