Webhooks

نظرة عامة

تمكّن Webhooks تطبيقات الدمج المخصص من الاشتراك في الأحداث الموجودة في Workplace وتلقي تحديثات في الوقت الحقيقي. وعند حدوث أي تغيير في Workplace، يتم إرسال طلب HTTPS POST إلى عنوان URL للاستدعاء لكل تطبيق دمج مخصص مشترك في موضوع webhook ذي الصلة.

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

يتم توفير دعم Webhook لـ Workplace بواسطة إطار العمل نفسه الذي يدير أحداث Webhooks في Graph API.

الاشتراك في موضوعات Webhook

يوفر مربع الحوار تعديل الدمج المخصص علامات تبويب لكل موضوع من موضوعات webhook المتوفرة لدى التطبيقات على Workplace.

قسم Webhooks في مربع الحوار "تعديل الدمج المخصص"

لإضافة اشتراك webhook جديد حول موضوع محدد، قم بتوفير عنوان URL للاستدعاء ورمز التحقق من الصحة ثم حدّد حقول الاشتراك التي تحتاج إليها للوظائف التي سيوفرها تطبيقك.

لا يمكنك سوى الاشتراك في عنوان URL واحد لكل موضوع webhook، ولكن يمكنك استخدام عنوان URL نفسه لموضوعات متعددة.

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

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

سيتم إلحاق سلسلة استعلام بعنوان URL هذا مع تضمين المعلمات التالية:

hub.mode - يتم إدخال السلسلة "subscribe" في هذه المعلمة
hub.challenge - سلسلة عشوائية
hub.verify_token - قيمة verify_token التي حددتها عند إنشاء الاشتراك

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

تتحقق من أن القيمة hub.verify_token تطابق السلسلة التي قمت بتعيينها في الحقل "رمز التحقق من الصحة" عند تكوين webhook.
تستجيب بالقيمة hub.challenge.

أمان حدث Webhook

يتم إجراء كل استدعاءات webhook لعناوين URL للاستدعاء المحددة بواسطة المطوّر عبر HTTPS، مما يضمن أمانًا على مستوى النقل لحمولات بيانات webhook.

لتوفير مستوى إضافي من الأمان، يتم تضمين X-Hub-Signature-256 لعنوان HTTP في كل حمولة بيانات POST، والذي يجب استخدامه للتحقق من أن حمولة البيانات مصدرها خادم Meta.

للحصول على تفاصيل كاملة حول هذا السلوك، ارجع إلى وثائق إطار عمل Webhook.

الاشتراك في أحداث webhooks باستخدام استدعاء واجهة API

يجب إجراء استدعاءات واجهة API لقراءة اشتراكات webhook أو تعديلها باستخدام رمز تطبيق بدلاً من رمز الدمج المخصص معتاد. ويمكن إنشاء رمز التطبيق عن طريق الربط بين معرف التطبيق والرمز '|' والمفتاح السري للتطبيق.

على سبيل المثال:

البيانات	String (سلسلة)
معرف التطبيق	504221332732118
المفتاح السري للتطبيق	d76ab3f35f3ff5aa6ffdc8637a660d2ea7
رمز التطبيق:	504221332732118\|d76ab3f35f3ff5aa6ffdc8637a660d2ea7

الحصول على اشتراكات webhook الحالية (باستخدام رمز التطبيق)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

إضافة اشتراك webhook جديد (باستخدام رمز التطبيق)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

استكشاف أخطاء اشتراكات الصفحة/التطبيق وإصلاحها

في الحالات التي لا يتم فيها تلقي webhooks كما هو متوقع، يُوصى بالتحقق من إعداد الاشتراك بين الصفحة والتطبيق بشكل صحيح. ويجب إعداد هذا تلقائيًا، لكن في بعض الحالات يمكن أن يفشل الأمر. على سبيل المثال، إذا فشل تسليم webhook لفترة زمنية طويلة، فيمكن إزالة هذا الاشتراك. وبالنسبة لتطبيقات الجهات الخارجية، سيؤدي هذا إلى ظهور تنبيه في لوحة معلومات التطبيق.

للتحقق من هذا الاشتراك، تتوفر استدعاءات واجهة API التالية:

الحصول على اشتراك الصفحة/التطبيق الحالي (باستخدام رمز الصفحة)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

لإعادة إنشاء هذا الاشتراك، تتوفر استدعاءات API التالية:

إعادة إنشاء اشتراك الصفحة/التطبيق الحالي (باستخدام رمز الصفحة)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

موضوعات Webhook

يتم تجميع النشاط على Workplace في الموضوعات. ويتضمن كل موضوع عددًا من الحقول التي ترتبط بأحداث تتعلق بموضوع محدد. يمكن للتطبيقات الاشتراك في تحديثات webhook حول كل موضوع ولحقول محددة ضمن كل موضوع.

توفر Workplace حاليًا webhooks للموضوعات والمجموعات التالية:

الصفحة

تتوفر المزيد من المعلومات في المستندات المرجعية لموضوع الصفحة.

حقل الاشتراك	السلوك
`mention`	يتم التشغيل عند ذكر صفحة دمج مخصص (برنامج تلقائي) في مجموعة.
`messages`	يتم التشغيل عند مراسلة صفحة دمج مخصص (برنامج تلقائي) في Work Chat.
`message_deliveries`	يتم التشغيل عند تسليم رسالة مرسلة بواسطة صفحة دمج مخصص (برنامج تلقائي).
`messaging_postbacks`	يتم التشغيل عند الضغط على زر الرد الجاهز في Work Chat.
`message_reads`	يتم التشغيل عندما يقرأ المستلم رسالة من صفحة دمج مخصص (برنامج تلقائي).

المجموعات

تتوفر المزيد من المعلومات في المستندات المرجعية لموضوع المجموعة.

حقل الاشتراك	السلوك
`posts`	يتم التشغيل عند إضافة منشور في مجموعة أو تحديثه أو حذفه.
`comments`	يتم التشغيل في كل مرة تتم فيها إضافة تعليق جديد على منشور في مجموعة أو تحديثه أو حذفه.
`membership`	يتم التشغيل عند تغيير عضوية المجموعة.
`membership_requests`	يتم التشغيل عند طلب المستخدم لعضوية المجموعة.

المستخدم

تتوفر المزيد من المعلومات في المستندات المرجعية لموضوع المستخدم.

حقل الاشتراك	السلوك
`status`	يتم التشغيل عندما ينشر المستخدم حالة جديدة في الملف الشخصي أو يعدلها. ويتضمن هذا المنشورات الموجودة في يوميات المستخدم.
`events`	يتم التشغيل في كل مرة ينشئ فيها المستخدم حدثًا أو يقبله أو يرفضه.
`message_sends`	يتم التشغيل في كل مرة يرسل فيها المستخدم رسالة Workplace Chat.
`message_unsends`	يتم التشغيل في كل مرة يزيل فيها المستخدم رسالة Workplace Chat للجميع في سلسلة منشورات.
`timeline_comments`	يتم التشغيل في كل مرة يوجد فيها تعليق على منشور في يوميات المستخدم.

الأمان

تتوفر المزيد من المعلومات في المستندات المرجعية لموضوع الأمان.

`admin_activity`

يتم تشغيل الأحداث عند إضافة مسؤول أو إزالته من مجتمع Workplace

الحدث	السلوك
`admin_set_to_unclaimed`	قام المسؤول بتعيين حالة حساب المستخدم إلى غير مُطالب به، من لوحة التحكم أو عبر واجهة API إدارة الحساب.
`admin_force_log_out`	فرض المسؤول على المستخدم تسجيل الخروج عبر كل الأجهزة من لوحة التحكم.
`admin_deactivate`	قام المسؤول بإلغاء تنشيط حساب من لوحة التحكم أو عبر واجهة API إدارة الحساب.
`admin_activate_account`	قام المسؤول بتنشيط حساب من لوحة التحكم أو عبر واجهة API إدارة الحساب.
`force_password_reset`	فرض المسؤول على المستخدم إعادة تعيين كلمة السر الخاصة به من لوحة التحكم.
`admin_create_account`	أنشأ المسؤول حسابًا من لوحة التحكم.

`compromised_credentials`

يتم تشغيل الأحداث عندما نشتبه في احتمالية تعرض كلمات سر Workplace لبعض حسابات المستخدمين في المجتمع للخطر.

الحدث	السلوك
`found_compromised_credentials`	عثر Workplace على بيانات اعتماد مخترقة.

`files`

يتم تشغيل الأحداث بناءً على نشاط ملف Workplace.

الحدث	السلوك
`group_file_upload`	قام المستخدم بتحميل ملف في مجموعة.
`group_file_download`	قام المستخدم بتنزيل ملف من مجموعة.
`file_upload_malware_found`	تم العثور على ملف تم تحميله يحتوي على برنامج ضار.

`groups`

يتم تشغيل الأحداث عندما يقوم الشخص بإنشاء مجموعة متعددة الشركات في Workplace أو الانضمام لها.

الحدث	السلوك
`mcg_join`	انضم مستخدم ما في المجتمع إلى مجموعة متعددة الشركات (MCG).
`mcg_create`	أنشأ مستخدم ما في المجتمع مجموعة متعددة الشركات (MCG).

`integrations`

يتم تشغيل الأحداث عندما يحاول المسؤول إنشاء خصائص الدمج أو تغييرها.

الحدث	السلوك
`custom_integration_create`	أنشأ أحد المسؤولين دمجًا مخصصًا.
`custom_integration_edit`	قام أحد المسؤولين بتعديل دمج مخصص.
`custom_integration_delete`	حذف أحد المسؤولين دمجًا مخصصًا.
`custom_integration_token_reset`	أنشأ أحد المسؤولين رمز وصول جديدًا لدمج مخصص.
`content_app_install`	أنشأ المستخدم دمج محتوى.
`content_app_uninstall`	ألغى المستخدم تثبيت دمج المحتوى.

`invites`

يتم تشغيل الأحداث عندما ينضم شخص ما إلى Workplace عبر الدعوة الذاتية.

الحدث	السلوك
`coworker_invite_sent`	قام المستخدم بدعوة زميل عمل للانضمام إلى المجتمع.
`self_invite_sent`	طلب المستخدم بريد إلكتروني لدعوة نفسه.

`passwords`

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

الحدث	السلوك
`password_change`	تم تغيير كلمة سر المستخدم نتيجة لاستكمال استرداد كلمة السر أو عبر إعدادات حسابه.
`password_reset_request`	تم بدء تدفق استرداد كلمة سر المستخدم وتم إرسال رمز إلى عنوان البريد الإلكتروني للمستخدم.
`password_reset_wrong_code`	أدخل مستخدم رمز استرداد غير صحيح لإعادة تعيين كلمة السر.
`password_reset_success`	اكتمل تدفق استرداد كلمة سر المستخدم بنجاح.

`sessions`

يتم تشغيل الأحداث عندما يسجل شخص ما الدخول أو الخروج من Workplace.

الحدث السلوك

الحدث	السلوك
`log_in`	سجّل المستخدم الدخول إلى Workplace باستخدام كلمة السر أو تسجيل الدخول الأحادي إما على الويب (www) أو تطبيقات الهواتف المحمولة.
`log_out`	سجّل المستخدم الخروج من Workplace باستخدام كلمة السر أو تسجيل الدخول الأحادي إما على الويب (www) أو تطبيقات الهواتف المحمولة. لا يتضمن تسجيل الخروج الإجباري الذي بدأه المسؤول (راجع `admin_force_log_out`)

log_in

سجّل المستخدم الدخول إلى Workplace باستخدام كلمة السر أو تسجيل الدخول الأحادي إما على الويب (www) أو تطبيقات الهواتف المحمولة.

log_out

سجّل المستخدم الخروج من Workplace باستخدام كلمة السر أو تسجيل الدخول الأحادي إما على الويب (www) أو تطبيقات الهواتف المحمولة.

لا يتضمن تسجيل الخروج الإجباري الذي بدأه المسؤول (راجع admin_force_log_out)

`two_factor`

يتم تشغيل الأحداث عندما يحاول شخص ما تمكين المصادقة الثنائية أو تعطيلها.

الحدث	السلوك
`two_factor_enable`	قام المستخدم بتمكين المصادقة الثنائية من علامة تبويب الإعدادات. ولا يتم تسجيل هذا عندما يؤكد شخص ما على هاتف معين، ولكنه يشير إلى أنه تم تمكين الميزة.
`two_factor_disable`	قام المستخدم بتعطيل المصادقة الثنائية من علامة تبويب الإعدادات. ولا يتم تسجيل هذا عندما يقوم شخص ما بتعطيل مصادقة ثنائية لهاتف معين، ولكنه يشير إلى أنه تم تعطيل الميزة.
`add_two_factor_phone`	قام المستخدم بإضافة هاتف مستخدم للمصادقة الثنائية وتأكيده.
`two_factor_code_success`	أدخل المستخدم رمزًا ثنائيًا صالحًا عند تسجيل الدخول إلى موقع ويب Workplace أو موقع ويب الهواتف المحمولة
`two_factor_code_failure`	أدخل المستخدم رمزًا ثنائيًا غير صالح عند تسجيل الدخول إلى موقع ويب Workplace أو موقع ويب الهواتف المحمولة
`two_factor_code_success_m`	أدخل المستخدم رمزًا ثنائيًا صالحًا عند تسجيل الدخول إلى تطبيق Workplace للهواتف المحمولة بنظام Android أو iOS
`two_factor_code_failure_m`	أدخل المستخدم رمزًا ثنائيًا غير صالح عند تسجيل الدخول إلى تطبيق Workplace للهواتف المحمولة بنظام Android أو iOS

`reseller_events`

الأحداث المتعلقة بالموزعين.

الحدث	السلوك
`reseller_user_added`	يتيح للمستخدم الذي لا يتمتع بدور المسؤول في شركة الموزع الاطّلاع على وحدة التحكم لدى الموزع.
`reseller_user_removed`	لا يتيح للمستخدم الذي لا يتمتع بدور المسؤول في شركة الموزع الاطّلاع على وحدة التحكم لدى الموزع.
`reseller_invite_sent`	يدعو الموزع شركة أخرى ليتم ربطها به.
`reseller_invite_accepted`	تقبل الشركة دعوة الموزع لطلب ربطها.
`reseller_invite_declined`	ترفض الشركة دعوة الموزع لطلب ربطها.

الروابط

تتوفر المزيد من المعلومات في المستندات المرجعية لموضوع الرابط

الحدث	السلوك
`preview`	بيانات التعريف حول المستخدم الذي يطلب الوصول إلى الروابط القابلة للمشاركة.
`collection`	بيانات التعريف للرابط الذي تتم مشاركته على Workplace لإنشاء معاينة.

مكتبة المعرفة

تتوفر المزيد من المعلومات في مستندات واجهة Graph API لفئة مكتبة المعرفة.

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