Skip to main content
الـ webhooks هي الطريقة الموصى بها لاستقبال نتائج Monitor. عند تفعيل Monitor، يرسل Pubrio طلب POST بحمولة JSON إلى الرابط الذي ضبطته — في الوقت الفعلي.

المتطلبات الأساسية

  • مفتاح Pubrio API بصلاحية الوصول إلى Monitor
  • نقطة طرفية HTTPS متاحة للعموم (أو رابط اختبار من usewebhook.com)
اختبار سريع: استخدم usewebhook.com لتوليد رابط webhook مؤقت ومجاني. يمكنك فحص كل حمولة واردة دون نشر أي شيء.

الخطوة 1: إنشاء Monitor بوجهة Webhook

الاستجابة:
يضيف الكائن headers ترويسات HTTP مخصصة إلى كل تسليم (مفيد للمصادقة). ويضيف الكائن body حقولًا مخصصة إلى جذر حمولة الـ webhook.
احفظ signature من الاستجابة — ستحتاجه للتحقق من الحمولات الواردة. لا يُعاد إلا وقت الإنشاء، عبر نقطة كشف التوقيع، أو من البحث عن Monitor مع is_signature_reveal: true.

الخطوة 2: التحقق من اتصال Webhook

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

الخطوة 3: الاختبار ببيانات حقيقية

بمجرد التحقق من الاتصال، فعّل تشغيلة حقيقية باستخدام نقطة Process Try. يجلب هذا إشارات فعلية ويسلّمها إلى webhook الخاص بك — استخدم tried_at بتاريخ ماضٍ قريب لضمان توفر البيانات:
بخلاف التحقق، تشغّل نقطة try فحصًا حقيقيًا وتستهلك أرصدة. استخدمها للتأكد من وصول الحمولات الحقيقية بشكل صحيح وللحصول على تقدير سريع للنتائج قبل بدء الفحص المجدول.

الخطوة 4: التحقق من التوقيعات

لكل Monitor توقيع فريد للتحقق من أن الحمولات الواردة صادرة فعلًا من Pubrio.
تحمل كل عملية تسليم ترويستين: x-pubrio-signature (السر المكشوف أعلاه) وx-pubrio-signature-256 (HMAC-SHA256 بصيغة سداسية عشرية لجسم الطلب الخام بمفتاح ذلك السر). تحقّق من HMAC على البايتات المستلمة قبل تحليل JSON.

بنية حمولة Webhook

تختلف الحمولات باختلاف detection_mode الخاص بالـ Monitor:
في وضع signal_first، تحتوي الحمولة على مصفوفة signals في المستوى الأعلى:
يحتوي كل إدخال إشارة على تفاصيل الإشارة والشركات والأشخاص المرتبطين بها بعد الإثراء.
تظهر حقول body المخصصة من destination_config عند جذر الحمولة (مثل "pipeline": "my-webhook" عند ضبطها في وجهتك).

إشارات التوسع

إلى جانب jobs وnews وadvertisements، يمكن لـ Monitor مراقبة إشارات التوسع — الدليل المؤرَّخ على أن شركة تدخل أو تنمو في سوق جديدة. أضِف expansions إلى signal_types:
تستخدم مرشحات التوسع مفردات البحث في التوسع، لا مفردات الوظائف/الأخبار/الإعلانات — froms وtos للممر، بالإضافة إلى stages وscopes وmomentum وfreshness وsignal_types وsignal_subtypes وsignal_strengths وsource_types وwindow_days. احصل على الأسماء القياسية الصالحة من مرجع التوسع.
يسلّم الويب هوك إشارات التوسع بوحدة سجل المراقب. في وحدة signal الافتراضية (signal_first) يكون كل إدخال إشارة خام واحدة (HIRE، AD، OFFICE…) يحمل companies[0] فيها بطاقة (الشركة، السوق)، وcountry_code هو السوق. اضبط record_unit: "company" لاستلام إدخال واحد لكل شركة مع إشاراتها متداخلة. ملخص البريد يجمّع دائمًا حسب الشركة والسوق.

البصمة السحابية

DNS هي إشارة البصمة السحابية — أي إنشاء الشركة بنية سحابية أو استضافة في سوق ما. ضيّق مراقب التوسّع عبر signal_types داخل مرشّحات التوسّع:
يحمل كل إرسال evidence_url، وهي صفحة Pubrio تدعم الإشارة. ولا تتضمّن الحمولة أي تفاصيل خام عن البنية التحتية. لتلقي المضيفين أنفسهم كتدفق أحداث خام بمرشحات المزوّد والمنطقة والمدينة، استخدم نوع الإشارة المخصص cloud_footprints أدناه.

حمولة إشارة التوسع

توجد معاني كل حقل على حدة في مرجع حقول التوسع. ولسحب نفس الصفوف عند الطلب بدلًا من انتظار التفعيل، استخدم البحث في إشارات التوسع.

إشارات البصمة السحابية

أضف cloud_footprints إلى signal_types لتتلقى سجلاً لكل مضيف تنشئه الشركة في سوق خارج بلدها: خادم جديد لدى مزوّد سحابة أو استضافة، أو خادم انتقل إلى منطقة أو بلد آخر. إنها الأدلة البنيوية نفسها التي تقرأها إشارة التوسع DNS، لكنها تُسلَّم كتدفق أحداث خام لا كمرحلة سوق: كل مضيف بترتيب وصوله، بمرشحات البصمة الخاصة، ومن دون مرحلة أو درجة أو نافذة.
تحمل كل signal الحقول provider وcloud_region وcity وnovelty وcountry_code وcountry_name وevent_date وdisplay_label مترجمة مثل AWS · Frankfurt وevidence_url. لا تُضمَّن أسماء المضيفين الخام ولا عناوين IP أبداً. بنية السوق المحلية ليست في هذا التدفق.

قواعد التسليم

ما هو السجل الواحد

السجل هو ما تعدّه الحدود وما يمثّل إدخال تسليم واحدًا. افتراضيًا يتبع وضع الاكتشاف: signal_first يسلّم إشارات (إدخال signals[] لكل وظيفة أو إعلان أو مقال أو إشارة توسع)، وcompany_first يسلّم شركات (إدخال companies[] لكل شركة مع إشاراتها متداخلة). اضبط record_unit للاختيار صراحة؛ مثلًا record_unit: "company" على مراقب إعلانات signal_first يسلّم إدخالًا واحدًا لكل معلن بدل إدخال لكل إعلان.

استبعاد الشركات

excluded_companies (مع excluded_domains وexcluded_linkedin_urls المحلولة بنفس طريقة companies) قائمة لا تُسلَّم أبدًا: تُحذف الشركة المستبعدة قبل الإثراء والمحاسبة في وضعي الاكتشاف، وتتخطاها قائمة متابعة company_first ما دامت في القائمة. حتى 100,000 شركة لكل مراقب، بما يكفي لتصدير العملاء الحاليين من CRM. في Update Monitor أرسل companies_mode أو excluded_companies_mode بقيمة add / remove لتغيير الإدخالات المرسلة فقط دون إعادة إرسال القائمة كاملة.

الحدود

تُقرأ قائمة بأي حجم صفحةً صفحة: Company Search مع company_groups: [source_group_id] (أو excluded_group_id)، وكلا المعرّفين يعيدهما Lookup Monitor الذي يعيد القوائم الكاملة أيضاً.

الأحدث أولاً

افتراضياً يسلّم المونيتور بترتيب الوصول، الأقدم أولاً، ويُرحّل الحد الأقصى ما تبقّى إلى التشغيل التالي، فتُعالَج تراكمات اليوم قبل الإشارات الأحدث. اضبط is_newest_first: true لعكس ذلك: يسلّم كل تشغيل أحدث السجلات المطابقة، وما يستبعده الحد الأقصى يُتخطّى نهائياً ولا يُصطفّ أبداً. ينطبق هذا على كل أنواع الإشارات وعلى مونيتور يستأنف بعد توقف أو بعد استنفاد الميزانية اليومية.

إزالة التكرار وإعادة التسليم

  • لا تُسلَّم الإشارة مرتين أبدًا. يسجّل كل تسليم ناجح مفاتيح الإشارات التي حملها، ويُسقط كل تشغيل أي مرشّح موجود في ذلك السجل، لجميع أنواع الإشارات. تحتفظ الوظائف والأخبار والإعلانات أيضًا بمؤشر لكل نوع، فلا تُجلب الإشارة المسلَّمة مرة أخرى أصلًا.
  • يضمن company_dedupe_days: N ظهور الشركة في تسليم واحد على الأكثر كل N يومًا عبر جميع أنواع إشارات المراقب؛ وتُتخطّى إشاراتها اللاحقة داخل النافذة.
  • تحمل كل حمولة metadata.monitor_log_id (صف هذه المحاولة في سجلات الإحصاءات) وmetadata.parent_monitor_log_id (null في المحاولة الأولى؛ وفي إعادة المحاولة، تلقائية كانت أو عبر إعادة محاولة المعالجة، معرّف المحاولة الأولى). لا تصلك الإشارات نفسها مرة أخرى إلا عبر إعادة محاولة كهذه، فأزل التكرار بناءً على parent_monitor_log_id || monitor_log_id. تعيد إعادة المحاولة افتراضياً إرسال حمولة المحاولة الأولى كما هي؛ أرسل is_use_original_payload: false لإعادة تطبيق القواعد الحالية أولاً (الاستبعادات وكلا السجلّين)، وعندها تُتخطّى إعادة المحاولة التي لم يبقَ فيها شيء بالرمز 40085.

وجهة البريد الإلكتروني

للفرق التي تفضّل التسليم عبر البريد الإلكتروني، اضبط destination_type على "email":
يدعم Pubrio تسليم بريد إلكتروني بعلامة بيضاء للوكالات والفرق. تواصل معنا لمعرفة المزيد عن تخصيص نطاق المرسل والهوية البصرية.

استكشاف الأخطاء وإصلاحها

  • تحقق من أن نقطتك الطرفية متاحة للعموم (وليست خلف جدار حماية أو VPN)
  • تأكد من أنها تُعيد رمز حالة 200 — أي رموز أخرى تُعامَل كإخفاق
  • استخدم نقطة التحقق من صحة Webhook لاختبار الاتصال
  • راجع سجلات الإحصاءات لرسائل الخطأ ورموز الاستجابة
إن كان webhook الخاص بك يُعيد رموزًا غير 200 باستمرار، يتوقف Monitor مؤقتًا بعد بلوغ max_failure_trigger من الإخفاقات المتتالية. أصلِح المشكلة وأعِد التفعيل عبر تحديث Monitor.
إن أخفق تسليم وكانت إعادة المحاولة مضبوطة، فقد تصلك نفس الحمولة عدة مرات. استخدم triggered_at أو معرّف السجل لإزالة التكرار من جهتك.
قلّل max_records_per_trigger للحد من عدد السجلات لكل تسليم. يمكنك أيضًا تضييق مرشحاتك لتقليل حجم الإشارات المطابقة.
آخر تعديل في ٨ أكتوبر ٢٠٢٦