البدء

يوضح هذا المستند كيفية إعداد حدث 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

أمان طبقة النقل المتبادلة (mTLS) هي طريقة للمصادقة المتبادلة.

يضمن mTLS أن الأطراف في كل جانب من اتصال الشبكة هم مطابقون لهويتهم حقًا من خلال التحقق من أن كل منهم لديه المفتاح الخاص الصحيح. توفر المعلومات الموجودة في شهادات TLS الخاصة بكل منهم إمكانية تحقق إضافية.

طريقة تكوين mTLS

بمجرد تمكين mTLS على اشتراكك في حساب واتساب للأعمال، ستقدم Meta شهادة عميل مع شهادة وسيطة موقعة. يتم استخدام كلا الشهادتين لإنشاء مصادقة TLS لطلبات أحداث Webhook المرسلة إلى خادمك. يمكن للخادم بعد ذلك التحقق من هوية مرسل هذه الطلبات بواسطة سلسلة الثقة والاسم المشترك (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 لديك لضمان الأمان.

مثال

استنادًا إلى إعدادات الخادم لديك، قد تختلف الخطوات أعلاه في التفاصيل. سنوضح ذلك من خلال مثالين، أحدهما لـ Nginx والآخر لـ AWS Application Load Balancer (ALB).

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

AWS Application Load Balancer (ALB)

تنزيل الشهادة الوسيطة (DigiCert SHA2 High Assurance Server CA) من DigiCert إلى حاوية S3. شهادة الجذر لن تكون مقبولة بواسطة AWS نظرًا إلى أنه تم توقيعها باستخدام خوارزمية SHA1withRSA؛ بينما تم توقيع الشهادة الوسيطة باستخدام SHA256withRSA وبالتالي يتم قبولها.
قم بتكوين مستقبل HTTPS في ALB لتمكين mTLS مع مخزن الثقة الذي يحتوي على الشهادة في حاوية S3 (مثال من لقطة شاشة).
في رمز التطبيق، استخرج CN من عنوان HTTP “X-Amzn-Mtls-Clientcert-Subject”، وتحقق من أنه يساوي “client.webhooks.fbclientcerts.com”.

الخطوات التالية

بعد أن تعرفت الآن على كيفية إعداد أحداث Webhooks، فقد تريد الرجوع إلى المستندات الإضافية الخاصة بنا والتي توضح الخطوات الإضافية التي يجب اتخاذها عند إعداد أحداث Webhooks في منتجات معينة: