إعداد Webhooks - Pubrio Documentation

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

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

مفتاح Pubrio API بصلاحية الوصول إلى Monitor
نقطة طرفية HTTPS متاحة للعموم (أو رابط اختبار من usewebhook.com)

اختبار سريع: استخدم usewebhook.com لتوليد رابط webhook مؤقت ومجاني. يمكنك فحص كل حمولة واردة دون نشر أي شيء.

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

curl -X POST https://api.pubrio.com/monitors/create \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "name": "My First Monitor",
    "detection_mode": "signal_first",
    "signal_types": ["jobs"],
    "signal_filters": [
      {
        "signal_type": "jobs",
        "filters": {
          "locations": ["US"]
        }
      }
    ],
    "destination_type": "webhook",
    "destination_config": {
      "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID",
      "headers": {
        "X-Custom-Auth": "your-secret-token"
      },
      "body": {
        "pipeline": "my-webhook"
      }
    },
    "max_records_per_trigger": 5,
    "profile_id": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/monitors/create",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY"
    },
    json={
        "name": "My First Monitor",
        "detection_mode": "signal_first",
        "signal_types": ["jobs"],
        "signal_filters": [
            {
                "signal_type": "jobs",
                "filters": {
                    "locations": ["US"]
                }
            }
        ],
        "destination_type": "webhook",
        "destination_config": {
            "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID",
            "headers": {
                "X-Custom-Auth": "your-secret-token"
            },
            "body": {
                "pipeline": "my-webhook"
            }
        },
        "max_records_per_trigger": 5,
        "profile_id": 1
    }
)

print(response.json())

const response = await fetch("https://api.pubrio.com/monitors/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    name: "My First Monitor",
    detection_mode: "signal_first",
    signal_types: ["jobs"],
    signal_filters: [
      {
        signal_type: "jobs",
        filters: {
          locations: ["US"]
        }
      }
    ],
    destination_type: "webhook",
    destination_config: {
      webhook_url: "https://usewebhook.com/YOUR_WEBHOOK_ID",
      headers: {
        "X-Custom-Auth": "your-secret-token"
      },
      body: {
        pipeline: "my-webhook"
      }
    },
    max_records_per_trigger: 5,
    profile_id: 1
  })
});

console.log(await response.json());

الاستجابة:

{
  "data": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My First Monitor",
    "detection_mode": "signal_first",
    "destination_type": "webhook",
    "is_active": true,
    "is_paused": false,
    "masked_signature": "7••••••••••••••••8df",
    "created_at": "2026-04-06T10:00:00.000Z",
    "signature": "71a2b3c4-d5e6-f789-0abc-def123456789"
  }
}

يضيف الكائن headers ترويسات HTTP مخصصة إلى كل تسليم (مفيد للمصادقة). ويضيف الكائن body حقولًا مخصصة إلى جذر حمولة الـ webhook.

احفظ signature من الاستجابة — ستحتاجه للتحقق من الحمولات الواردة. لا يُعاد إلا وقت الإنشاء، عبر نقطة كشف التوقيع، أو من البحث عن Monitor مع is_signature_reveal: true.

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

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

curl -X POST https://api.pubrio.com/monitors/webhook/validate \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "detection_mode": "signal_first",
    "signal_types": ["jobs"],
    "signal_filters": [
      {
        "signal_type": "jobs",
        "filters": { "locations": ["US"] }
      }
    ],
    "destination_type": "webhook",
    "destination_config": {
      "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID",
      "headers": { "X-Custom-Auth": "your-secret-token" },
      "body": { "pipeline": "my-webhook" }
    },
    "profile_id": 1
  }'

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

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

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

curl -X POST https://api.pubrio.com/monitors/process/try \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tried_at": "2026-01-01T00:00:00.000Z",
    "profile_id": 1
  }'

بخلاف التحقق، تشغّل نقطة try فحصًا حقيقيًا وتستهلك أرصدة. استخدمها للتأكد من وصول الحمولات الحقيقية بشكل صحيح وللحصول على تقدير سريع للنتائج قبل بدء الفحص المجدول.

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

لكل Monitor توقيع فريد للتحقق من أن الحمولات الواردة صادرة فعلًا من Pubrio.

curl -X POST https://api.pubrio.com/monitors/signature/reveal \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "profile_id": 1
  }'

{
  "data": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "signature": "71a2b3c4-d5e6-f789-0abc-def123456789"
  }
}

قارن هذا التوقيع مع monitor.monitor_id في الحمولات الواردة للتحقق من الأصالة.

بنية حمولة Webhook

تختلف الحمولات باختلاف detection_mode الخاص بالـ Monitor:

الإشارة أولًا (Signal First)
الشركة أولًا (Company First)

في وضع signal_first، تحتوي الحمولة على مصفوفة signals في المستوى الأعلى:

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Signal Monitor",
    "detection_mode": "signal_first",
    "signal_types": ["jobs", "news"],
    "signal_filters": [...],
    "company_filters": {...},
    "is_company_enrichment": true,
    "is_people_enrichment": true,
    "people_enrichment_configs": [...]
  },
  "metadata": {
    "total_signals": 3,
    "total_companies": 2,
    "total_people": 5
  },
  "triggered_at": "2026-04-05T20:29:43.832Z",
  "signals": [
    {
      "signal_type": "jobs",
      "signal": {
        "signal_type": "jobs",
        "job_search_id": "...",
        "companies": [
          {
            "domain_search_id": "...",
            "company_name": "...",
            "domain": "...",
            ...
          }
        ],
        ...
      },
      "companies": [
        {
          "domain_search_id": "...",
          "company_name": "...",
          "domain": "...",
          "logo_url": "...",
          "country_code": "...",
          "company_size": 5000,
          "industry": "...",
          "people": [...],
          "emails": [...],
          "phones": [...],
          ...
        }
      ]
    },
    {
      "signal_type": "news",
      "signal": {
        "signal_type": "news",
        "news_search_id": "...",
        "news_id": "...",
        "title": "...",
        "summary": "...",
        "published_at": "...",
        "source": "...",
        "category": "...",
        "companies": [...],
        ...
      },
      "companies": [...],
      ...
    },
    ...
  ]
}

يحتوي كل إدخال إشارة على تفاصيل الإشارة والشركات والأشخاص المرتبطين بها بعد الإثراء.

في وضع company_first، تحتوي الحمولة على مصفوفة companies في المستوى الأعلى ببيانات شركات مُثراة وإشارات متداخلة:

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Company Monitor",
    "detection_mode": "company_first",
    "signal_types": ["jobs", "news", "advertisements"],
    "signal_filters": [...],
    "company_filters": {...},
    "is_company_enrichment": true,
    "is_people_enrichment": true,
    "people_enrichment_configs": [...]
  },
  "metadata": {
    "total_signals": 4,
    "total_companies": 2,
    "total_people": 8
  },
  "triggered_at": "2026-04-03T17:45:27.228Z",
  "companies": [
    {
      "company_name": "Acme Corp",
      "domain": "acmecorp.com",
      "domain_search_id": "...",
      "country_code": "US",
      "logo_url": "...",
      "linkedin_name": "acmecorp",
      "company_size": 5200,
      "industry": "Enterprise Software",
      "estimated_revenue": 50000000,
      "founded_year": 2010,
      "company_address": "San Francisco, CA",
      "specialties": ["SaaS", "Cloud Computing", ...],
      "linkedin_url": "https://linkedin.com/company/...",
      "locations": ["US"],
      "signals": [
        {
          "signal_type": "news",
          "signal": {
            "news_id": "...",
            "title": "Acme Corp Launches New AI Product",
            "summary": "...",
            "published_at": "2026-04-03T16:35:00.000Z",
            "source": "techcrunch.com",
            "category": "launches",
            "news_category_name": "Product Launch",
            ...
          }
        },
        {
          "signal_type": "jobs",
          "signal": {
            "job_search_id": "...",
            ...
          }
        },
        ...
      ],
      "people": [
        {
          "name": "Jane Smith",
          "title": "VP of Engineering",
          "email": "[email protected]",
          ...
        },
        ...
      ],
      "emails": ["[email protected]", ...],
      "phones": ["+14155551234", ...],
      "contacts": [...],
      ...
    },
    ...
  ]
}

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

تظهر حقول body المخصصة من destination_config عند جذر الحمولة (مثل "pipeline": "my-webhook" عند ضبطها في وجهتك).

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

إلى جانب jobs وnews وadvertisements، يمكن لـ Monitor مراقبة إشارات التوسع — الدليل المؤرَّخ على أن شركة تدخل أو تنمو في سوق جديدة. أضِف expansions إلى signal_types:

{
  "name": "US market entries",
  "detection_mode": "signal_first",
  "signal_types": ["expansions"],
  "signal_filters": [
    {
      "signal_type": "expansions",
      "filters": {
        "tos": ["US"],
        "stages": ["expanding", "scaling"],
        "signal_strengths": ["high", "very_high"],
        "window_days": 30
      }
    }
  ],
  "destination_type": "webhook",
  "destination_config": {
    "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID"
  }
}

تستخدم مرشحات التوسع مفردات البحث في التوسع، لا مفردات الوظائف/الأخبار/الإعلانات — froms وtos للممر، بالإضافة إلى stages وscopes وmomentum وfreshness وsignal_types وsignal_subtypes وsignal_strengths وsource_types وwindow_days. احصل على الأسماء القياسية الصالحة من مرجع التوسع.

تُجمَّع إشارات التوسع حسب الشركة والسوق، لا حسب الإشارة. الشركة التي تدخل سوقين تنتج إدخالين، يحمل كل منهما الجدول الزمني الخاص بإشارات ذلك السوق.

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

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "US market entries",
    "detection_mode": "signal_first",
    "signal_types": ["expansions"],
    "signal_filters": [...]
  },
  "metadata": {
    "total_signals": 2,
    "total_companies": 1,
    "total_people": 0
  },
  "triggered_at": "2026-08-14T09:12:04.551Z",
  "signals": [
    {
      "signal_type": "expansions",
      "signal": {
        "signal_type": "expansions",
        "expansion_signal_id": 90211,
        "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
        "country_code": "US",
        "signal_type_slug": "HIRE",
        "signal_type_name": "Hiring",
        "signal_subtype_slug": "country_manager",
        "signal_strength_slug": "high",
        "polarity": "expansion",
        "event_date": "2026-08-13T14:00:00.000Z",
        "event_date_precision": "day",
        "source_type": "linkedin",
        "display_label": "Hired Country Manager",
        "evidence_url": "https://linkedin.com/company/example-corp",
        "metadata": {...},
        "companies": [
          {
            "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
            "company_name": "Example Corp",
            "domain": "example.com",
            "stage_name": "Expanding",
            "stage_description": "...",
            "home_country": "GB",
            "home_country_name": "United Kingdom",
            "target_country": "US",
            "target_country_name": "United States",
            "estimated_employees": 420,
            "linkedin_url": "https://linkedin.com/company/example-corp"
          }
        ]
      },
      "companies": [...]
    }
  ]
}

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

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

للفرق التي تفضّل التسليم عبر البريد الإلكتروني، اضبط destination_type على "email":

{
  "destination_type": "email",
  "destination_config": {
    "email": "[email protected]"
  }
}

يدعم Pubrio تسليم بريد إلكتروني بعلامة بيضاء للوكالات والفرق. تواصل معنا لمعرفة المزيد عن تخصيص نطاق المرسل والهوية البصرية.

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

Webhook لا يستقبل حمولات

تحقق من أن نقطتك الطرفية متاحة للعموم (وليست خلف جدار حماية أو VPN)
تأكد من أنها تُعيد رمز حالة 200 — أي رموز أخرى تُعامَل كإخفاق
استخدم نقطة التحقق من صحة Webhook لاختبار الاتصال
راجع سجلات الإحصاءات لرسائل الخطأ ورموز الاستجابة

تم إيقاف Monitor مؤقتًا بعد إخفاقات

إن كان webhook الخاص بك يُعيد رموزًا غير 200 باستمرار، يتوقف Monitor مؤقتًا بعد بلوغ max_failure_trigger من الإخفاقات المتتالية. أصلِح المشكلة وأعِد التفعيل عبر تحديث Monitor.

حمولات مكررة

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

الحمولة كبيرة جدًا

قلّل max_records_per_trigger للحد من عدد السجلات لكل تسليم. يمكنك أيضًا تضييق مرشحاتك لتقليل حجم الإشارات المطابقة.

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

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

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

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

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

​بنية حمولة Webhook

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

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

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

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

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

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

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

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

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

بنية حمولة Webhook

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

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

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

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