เริ่มต้นใช้งาน

เอกสารนี้จะอธิบายวิธีตั้งค่า Webhook ซึ่งจะแจ้งให้คุณทราบทุกครั้งที่ผู้ใช้แอพของคุณเผยแพร่การเปลี่ยนแปลงกับรูปภาพของผู้ใช้ เมื่อคุณเข้าใจวิธีตั้งค่า Webhook นี้แล้ว คุณจะทราบวิธีตั้งค่า Webhooks ทั้งหมด

ในการตั้งค่า Webhook ใดๆ ก็ตาม คุณจะต้องทำสิ่งต่อไปนี้

สร้างตำแหน่งข้อมูลบนเซิร์ฟเวอร์ที่ปลอดภัยที่สามารถประมวลผลคำขอ HTTPS ได้
กำหนดค่าผลิตภัณฑ์ Webhooks ในแดชบอร์ดของแอพในแอพของคุณ

ซึ่งคุณสามารถดูคำอธิบายโดยละเอียดของขั้นตอนเหล่านี้ได้ด้านล่าง

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.

การกำหนดค่าผลิตภัณฑ์ Webhooks

เมื่อตำแหน่งข้อมูลหรือแอพตัวอย่างของคุณพร้อมแล้ว ให้ใช้แดชบอร์ดของแอพของแอพคุณเพื่อเพิ่มและกำหนดค่าผลิตภัณฑ์ Webhooks นอกจากนี้คุณยังสามารถดำเนินการดังกล่าวได้โดยใช้โปรแกรม โดยใช้ตำแหน่งข้อมูล /{app-id}/subscriptionsสำหรับ Webhooks ทั้งหมดยกเว้น Instagram

ในตัวอย่างนี้ เราจะใช้แดชบอร์ดเพื่อกำหนดค่า Webhook ที่สมัครรับข้อมูลการเปลี่ยนแปลงในรูปภาพของผู้ใช้แอพของคุณ

ใน "แดชบอร์ดของแอพ" ให้ไปที่ "ผลิตภัณฑ์" > "Webhooks" เลือก "ผู้ใช้" จากเมนูดร็อปดาวน์ จากนั้นคลิก "สมัครรับข้อมูลอ็อบเจ็กต์นี้"
การเลือกอ็อบเจ็กต์ผู้ใช้
ป้อน URL ของตำแหน่งข้อมูลของคุณลงในช่อง URL การเรียกกลับ และป้อนสตริงลงในช่อง "โทเค็นการตรวจสอบยืนยัน" เราจะรวมสตริงนี้ไว้ในคำขอให้ตรวจสอบยืนยันทั้งหมด หากคุณกำลังใช้หนึ่งในแอพตัวอย่างของเรา แอพนี้ควรเป็นสตริงเดียวกับที่คุณใช้สำหรับตัวแปรการกำหนดค่า TOKEN ของแอพคุณ
หากคุณต้องการให้เพย์โหลดการแจ้งเตือนเหตุการณ์รวมชื่อของช่องที่เปลี่ยนแปลงไปพร้อมกับค่าใหม่ ให้สลับปุ่ม "รวมค่า" เป็น "ใช่"
การป้อน URL ของตำแหน่งข้อมูลและสตริงโทเค็นการตรวจสอบยืนยัน
เมื่อคุณคลิก "ตรวจสอบยืนยันและบันทึก" เราจะส่งคำขอให้ตรวจสอบยืนยันไปที่ตำแหน่งข้อมูลของคุณซึ่งคุณจะต้องตรวจสอบ หากตำแหน่งข้อมูลของคุณตรวจสอบคำขอสำเร็จ คุณควรเห็นดังต่อไปนี้
การตรวจสอบสำเร็จ
ขั้นตอนสุดท้ายคือการสมัครรับข้อมูลแต่ละช่อง สมัครรับข้อมูลจากช่อง photos และส่ง "การแจ้งเตือนเหตุการณ์" ขั้นทดสอบ
การสมัครรับข้อมูลจากช่อง "รูปภาพ" บนอ็อบเจ็กต์ "ผู้ใช้"
หากตำแหน่งข้อมูลของคุณได้รับการตั้งค่าอย่างถูกต้อง ตำแหน่งข้อมูลของคุณควรตรวจสอบความถูกต้องของเพย์โหลดและใช้โค้ดใดก็ตามที่คุณตั้งไว้เมื่อตรวจสอบเสร็จเรียบร้อย หากคุณกำลังใช้แอพตัวอย่างของเรา ให้โหลด URL ของแอพในเว็บเบราว์เซอร์ของคุณ โดยระบบควรแสดงเนื้อหาของเพย์โหลดดังต่อไปนี้
แอพตัวอย่างที่แสดงเพย์โหลดการแจ้งเตือนขั้นทดสอบ

mTLS สำหรับ Webhooks

TLS ร่วมกัน (Mutual TLS หรือ mTLS) คือวิธีการยืนยันตัวตนร่วมกัน

mTLS จะช่วยรับรองว่าผู้ใช้แต่ละฝั่งของเครือข่ายเป็นบุคคลเดียวกับที่กล่าวอ้างไว้ โดยตรวจสอบยืนยันว่าทั้ง 2 ฝ่ายมีคีย์ส่วนบุคคลที่ถูกต้อง ข้อมูลในใบรับรอง TLS ของแต่ละฝ่ายจะให้การตรวจสอบยืนยันเพิ่มเติม

วิธีกำหนดค่า mTLS

เมื่อคุณเปิดใช้งาน mTLS ในการสมัครรับข้อมูลบัญชี WhatsApp Business แล้ว Meta ก็จะส่งใบรับรองไคลเอ็นต์พร้อมใบรับรองระดับกลางที่มีการลงนาม ระบบจะใช้ใบรับรองทั้งสองนี้เพื่อสร้างแฮนด์เชค TLS ของคำขอ Webhook ไปยังเซิร์ฟเวอร์ของคุณ จากนั้น เซิร์ฟเวอร์ของคุณจะยืนยันตัวตนของผู้ส่งคำขอเหล่านี้ได้โดยใช้เชนความน่าเชื่อถือ (Trust Chain) และชื่อทั่วไป (CN)

ใบรับรองไคลเอ็นต์ได้รับการลงนามโดยใบรับรอง CA ระดับกลาง (DigiCert SHA2 High Assurance Server CA) ตามด้วยใบรับรอง CA ระดับรูท (DigiCert High Assurance EV Root CA) โปรดทราบว่า ใบรับรองระดับกลางจะลงนามใบรับรองสำหรับ graph.facebook.com ด้วย

การตรวจสอบยืนยันใบรับรองไคลเอ็นต์

หลังจากตั้งค่า HTTPS เพื่อรับคำขอ Webhook ให้ทำตามขั้นตอนต่อไปนี้เพื่อตรวจสอบยืนยันใบรับรองไคลเอ็นต์และชื่อทั่วไปของใบรับรองนั้นๆ client.webhooks.fbclientcerts.com:

ติดตั้งใบรับรองระดับรูท
ตรวจสอบยืนยันใบรับรองไคลเอ็นต์เทียบกับใบรับรองระดับรูท
ตรวจสอบยืนยันชื่อทั่วไป (client.webhooks.fbclientcerts.com) ของใบรับรองไคลเอ็นต์

หมายเหตุ: เซิร์ฟเวอร์ที่ได้รับ Webhooks จะต้องใช้ HTTPS และเราจะตรวจสอบยืนยันใบรับรองจากเซิร์ฟเวอร์ HTTPS ของคุณเสมอเพื่อความปลอดภัย

ตัวอย่าง

ขั้นตอนข้างต้นจะมีรายละเอียดแตกต่างกันไปตามการตั้งค่าเซิร์ฟเวอร์ของคุณ เราจะแสดงให้เห็นโดยใช้ตัวอย่าง 2 รายการ รายการแรกเป็นของ Nginx ส่วนอีกรายการหนึ่งเป็นของ Application Load Balancer (ALB) จาก AWS

Nginx

ดาวน์โหลดใบรับรองระดับรูท (DigiCert High Assurance EV Root CA) จาก DigiCert ไปยังเซิร์ฟเวอร์ของคุณ เช่น /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem

เปิด mTLS โดยใช้คำสั่ง Nginx (ตัวอย่างภาพหน้าจอ)

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

ตรวจสอบยืนยันว่า CN จากตัวแปรแบบฝังของ Nginx $ssl_client_s_dn คือ "client.webhooks.fbclientcerts.com" (ตัวอย่างภาพหน้าจอ)
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

Application Load Balancer (ALB) จาก AWS

ดาวน์โหลดใบรับรองระดับกลาง (DigiCert SHA2 High Assurance Server CA) จาก DigiCert ไปยังบักเก็ต S3 ใบรับรองระดับรูทไม่ได้รับการยอมรับจาก AWS เนื่องจากมีการลงนามโดยใช้อัลกอริทึม SHA1withRSA ในขณะที่ใบรับรองระดับกลางมีการลงนามโดยใช้ SHA256withRSA จึงได้รับการยอมรับ
กำหนดค่าตัวรับ HTTPS ใน ALB เพื่อเปิดใช้งาน mTLS ด้วยที่เก็บข้อมูลที่เชื่อถือได้ (Trust Store) ซึ่งมีใบรับรองในบักเก็ต S3 (ตัวอย่างภาพหน้าจอ)
ในโค้ดแอพพลิเคชั่นของคุณ ให้ดึงข้อมูล CN จากส่วนหัว HTTP “X-Amzn-Mtls-Clientcert-Subject” และตรวจสอบยืนยันว่าเป็น “client.webhooks.fbclientcerts.com”

ขั้นตอนถัดไป

เมื่อคุณรู้วิธีตั้งค่า Webhooks แล้ว คุณอาจต้องการอ้างอิงจากเอกสารเพิ่มเติมของเราที่อธิบายขั้นตอนเพิ่มเติมที่เกี่ยวข้องเมื่อทำการตั้งค่า Webhooks สำหรับผลิตภัณฑ์ที่เฉพาะเจาะจง