بدء الاستخدام

يوضح هذا المستند كيفية إعداد حدث Webhook الذي يخطرك عندما ينشر مستخدمو تطبيقك أي تغييرات على صور المستخدم الخاصة بهم. وبمجرد أن تدرك كيفية إعداد Webhook (إخطار الويب) هذا، ستعرف كيفية إعداد جميع إخطارات الويب Webhooks.

يتطلب منك إعداد أي حدث Webhook ما يلي:

1. إنشاء نقطة نهاية على خادم آمن يمكنه معالجة طلبات HTTPS.
2. تكوين منتج Webhooks في لوحة معلومات التطبيق لدى تطبيقك.

تتضح هذه الخطوات بالتفصيل أدناه.

إنشاء نقطة نهاية

يجب أن تتمكّن نقطة النهاية من معالجة نوعين من طلبات HTTPS وهما: طلبات التحقق وإشعارات الأحداث. ونظرًا لأن كلا الطلبين يستخدمان بروتوكولات HTTP، يجب أن يتوفر لدى خادمك شهادة TLS أو SSL صالحة تم تكوينها وتثبيتها بشكل صحيح. علمًا بأن الشهادات الموقّعة ذاتيًا غير مدعومة.

توضح الأقسام أدناه المحتويات التي سيتضمنها كل نوع من أنواع الطلبات وكيفية الاستجابة لها. وبدلاً من ذلك، يمكنك استخدام عينة التطبيق التي نوفرها والتي تم تكوينها بالفعل لمعالجة هذه الطلبات.

طلبات التحقق

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

عينة من طلب التحقق

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

ملاحظة:تحول لغة PHP النقاط (.) إلى شرطات سفلية (_) في أسماء المعلمات.

التحقق من صحة طلبات التحقق

عندما تتلقى نقطة النهاية لديك طلب تحقق، يجب أن:

• يتحقق من مطابقة القيمة hub.verify_token مع السلسلة التي قمت بتعيينها في الحقل رمز التحقق عندما تقوم بتكوين منتج Webhooks في لوحة معلومات التطبيق لديك (لم تقم بإعداد سلسلة الرمز هذه حتى الآن).
• تستجيب بالقيمة hub.challenge.

إذا كنت موجودًا في لوحة معلومات التطبيق لديك وتقوم بتكوين منتج Webhooks (وبالتالي، تشغيل طلب التحقق)، فستشير لوحة المعلومات إلى ما إذا كانت نقطة النهاية قد تحققت من صحة الطلب بشكل صحيح. وإذا كنت تستخدم نقطة النهاية /app/subscriptions بواجهة Graph API لتكوين منتج Webhooks، فستشير API إلى نجاح أو فشل الاستجابة.

إشعارات الأحداث

عندما تقوم بتكوين منتج Webhooks لديك، فستشترك في fields محددة بالنوع object (مثل، الحقل photos بالكائن user). وعندما يطرأ تغيير على أحد هذه الحقول، سنرسل إلى نقطة النهاية طلب POST يتضمن حمولة بيانات JSON يوضح التغيير.

علي سبيل المثال، إذا اشتركت في الحقل photos للكائن user ونشر أحد مستخدمي تطبيقك صورة، فسنرسل إليك طلب POST يبدو كما يلي:

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

محتويات حمولة البيانات

ستتضمن حمولات البيانات كائنًا يوضح التغيير. وعند تكوين منتج webhooks، يمكنك الإشارة إلى ما إذا كان يجب أن تتضمن حمولات البيانات أسماء الحقول التي تم تغييرها فقط أو إذا كانت يجب أن تتضمن القيم الجديدة أيضًا.

وسنقوم بتنسيق كل حمولات البيانات بلغة JSON بحيث يمكنك تحليل حمولة البيانات باستخدام تنسيق لغة JSON الشائع الذي يحلل الأساليب أو الحِزم.

ستتضمن معظم حمولات البيانات الخصائص الشائعة التالية، ولكن تختلف محتويات كل حمولة بيانات وبنيتها باختلاف حقول الكائن الذي تشترك فيه. راجع مستند المرجع الخاص بكل كائن لمعرفة الحقول التي سيتم تضمينها.

التحقق من صحة حمولات البيانات

نوقع كل حمولات بيانات إشعار الحدث بتوقيع SHA256، ونقوم بتضمين التوقيع في عنوان X-Hub-Signature-256 الخاص بالطلب المسبوق بتوقيع sha256=. ولا تحتاج إلى التحقق من صحة حمولة البيانات، ولكن من الأفضل إجراء ذلك.

للتحقق من صحة حمولة البيانات:

1. أنشئ توقيع SHA256 باستخدام حمولة البيانات والمفتاح السري للتطبيق في تطبيقك.
2. قارن توقيعك بالتوقيع الموجود في عنوان X-Hub-Signature-256 (كل ما يأتي بعد sha256=). في حالة مطابقة التوقيعات، تكون حمولة البيانات حقيقية.

الاستجابة لإشعارات الحدث

يجب أن تستجيب نقطة النهاية لكل إشعارات الحدث التي تتضمن 200 OK HTTPS.

معدل التكرار

يتم تجميع إشعارات الحدث وإرسالها في مجموعة تتضمن 1000 تحديث كحد أقصى. وعلى الرغم من ذلك، لا يمكن ضمان عملية التجميع، لذا تأكد من ضبط الخوادم لديك لمعالجة كل حدث Webhook على حدة.

إذا فشل أي تحديث تم إرساله إلى خادمك، فسنعيد المحاولة على الفور، ثم نكرر المحاولة عدة مرات بمعدل تكرار متناقص على مدار الـ 36 ساعة التالية. وفي هذه الحالات، يجب على خادمك معالجة إلغاء التكرار. علمًا بأنه سيتم تجاهل الاستجابات غير المعترف بها بعد مرور 36 ساعة.

ملاحظة: يكون معدل التكرار الذي يتم من خلاله إرسال إشعارات حدث Messenger مختلفًا. يُرجى الرجوع إلى وثائق Webhooks لمنصة Messenger لمزيد من المعلومات.

تكوين منتج Webhooks

بمجرد أن تصبح نقطة النهاية أو نموذج تطبيقك جاهزًا، استخدم لوحة معلومات التطبيق في تطبيقك لإضافة منتج Webhooks وتكوينه. ويمكنك أيضًا إجراء ذلك بطريقة برمجية عن طريق استخدام نقطة النهاية /{app-id}/subscriptions في جميع أحداث Webhooks باستثناء Instagram.

ففي هذا المثال، سنستخدم لوحة المعلومات لتكوين حدث Webhook الذي يشترك في أي تغييرات تطرأ على صور أحد مستخدمي تطبيقك.

1. في لوحة معلومات التطبيق، انتقل إلى المنتجات > Webhooks وحدّد المستخدم من القائمة المنسدلة، ثم انقر على الاشتراك في هذا الكائن.
   

   اختيار كائن المستخدم.

2. أدخل عنوان URL الخاص بنقطة النهاية في الحقل عنوان URL للاستدعاء، ثم أدخل سلسلة في الحقل رمز التحقق. وسنقوم بتضمين هذه السلسلة في كل طلبات التحقق. إذا كنت تستخدم واحدة من عينات التطبيقات التي نوفرها، فيجب أن تكون هذه هي السلسلة نفسها التي استخدمتها في متغير تكوين TOKEN بتطبيقك.

   إذا كنت تريد أن تتضمن حمولات بيانات إشعارات الأحداث أسماء الحقول التي تم تغييرها بالإضافة إلى قيمها الجديدة، فقم بتعيين مفتاح التبديل تضمين القيم على نعم.
   

   إدخال عنوان URL الخاص بنقطة النهاية وسلسلة رمز التحقق.

3. بمجرد أن تنقر على التحقق والحفظ، سنرسل إلى نقطة النهاية طلب تحقق يجب عليك أن تتحقق من صحته. وإذا تحققت نقطة النهاية من الطلب بنجاح، فيجب أن يظهر لك ما يلي:

   

   التحقق من الصحة ناجح.

4. تتمثل الخطوة الأخيرة في الاشتراك في الحقول الفردية. اشترك في الحقل photos، ثم أرسل إشعار حدث اختباريًا.

   

   الاشتراك في حقل الصور بكائن المستخدم.

   في حالة إعداد نقطة النهاية بشكل صحيح، يجب أن تتحقق من حمولة البيانات وتقوم بتنفيذ الرمز الذي قمت بإعدادها لتشغيله في حالة نجاح التحقق. وإذا كنت تستخدم عينة التطبيق التي نوفرها، فقم بتحميل عنوان URL الخاص بالتطبيق في متصفح الويب لديك. ويجب أن يعرض محتويات حمولة البيانات:

   

   عينة من التطبيق تعرض حمولة بيانات الإشعار الاختباري.

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

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

• أحداث Webhooks للحسابات الإعلانية
• أحداث Webhooks لشفافية الشهادات
• أحداث Webhooks في Instagram
• أحداث Webhooks لبيانات العملاء المحتملين
• أحداث Webhooks في Messenger
• أحداث Webhooks للصفحات
• أحداث Webhooks لعمليات الدفع
• أحداث Webhooks في واتساب