المتطلبات الأساسية
- مفتاح Pubrio API بصلاحية الوصول إلى Monitor
- نقطة طرفية HTTPS متاحة للعموم (أو رابط اختبار من usewebhook.com)
الخطوة 1: إنشاء Monitor بوجهة Webhook
headers ترويسات HTTP مخصصة إلى كل تسليم (مفيد للمصادقة). ويضيف الكائن body حقولًا مخصصة إلى جذر حمولة الـ webhook.
الخطوة 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)
- الشركة أولًا (Company First)
في وضع يحتوي كل إدخال إشارة على تفاصيل الإشارة والشركات والأشخاص المرتبطين بها بعد الإثراء.
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 تسليم بريد إلكتروني بعلامة بيضاء للوكالات والفرق. تواصل معنا لمعرفة المزيد عن تخصيص نطاق المرسل والهوية البصرية.
استكشاف الأخطاء وإصلاحها
Webhook لا يستقبل حمولات
Webhook لا يستقبل حمولات
- تحقق من أن نقطتك الطرفية متاحة للعموم (وليست خلف جدار حماية أو VPN)
- تأكد من أنها تُعيد رمز حالة
200— أي رموز أخرى تُعامَل كإخفاق - استخدم نقطة التحقق من صحة Webhook لاختبار الاتصال
- راجع سجلات الإحصاءات لرسائل الخطأ ورموز الاستجابة
تم إيقاف Monitor مؤقتًا بعد إخفاقات
تم إيقاف Monitor مؤقتًا بعد إخفاقات
إن كان webhook الخاص بك يُعيد رموزًا غير 200 باستمرار، يتوقف Monitor مؤقتًا بعد بلوغ
max_failure_trigger من الإخفاقات المتتالية. أصلِح المشكلة وأعِد التفعيل عبر تحديث Monitor.حمولات مكررة
حمولات مكررة
إن أخفق تسليم وكانت إعادة المحاولة مضبوطة، فقد تصلك نفس الحمولة عدة مرات. استخدم
triggered_at أو معرّف السجل لإزالة التكرار من جهتك.الحمولة كبيرة جدًا
الحمولة كبيرة جدًا
قلّل
max_records_per_trigger للحد من عدد السجلات لكل تسليم. يمكنك أيضًا تضييق مرشحاتك لتقليل حجم الإشارات المطابقة.
