> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# إعداد Webhooks

> اضبط وجهات الـ webhook، وتحقق من صحة النقاط الطرفية، وتحقق من التوقيعات، وتعامل مع الحمولات.

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

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

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

<Tip>
  **اختبار سريع:** استخدم [usewebhook.com](https://usewebhook.com) لتوليد رابط webhook مؤقت ومجاني. يمكنك فحص كل حمولة واردة دون نشر أي شيء.
</Tip>

***

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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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());
  ```
</CodeGroup>

**الاستجابة:**

```json theme={null}
{
  "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.

<Tip>
  احفظ `signature` من الاستجابة — ستحتاجه للتحقق من الحمولات الواردة. لا يُعاد إلا وقت الإنشاء، عبر نقطة [كشف التوقيع](/ar/api-reference/endpoint/monitors/signature_reveal)، أو من [البحث عن Monitor](/ar/api-reference/endpoint/monitors/lookup) مع `is_signature_reveal: true`.
</Tip>

***

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

استخدم نقطة [التحقق من صحة Webhook](/ar/api-reference/endpoint/monitors/webhook_validate) لاختبار أن نقطتك الطرفية قابلة للوصول. يرسل هذا **حمولة نموذجية** ببيانات نائبة — دون استهلاك أي أرصدة أو جلب إشارات حقيقية.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

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

***

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

بمجرد التحقق من الاتصال، فعّل تشغيلة حقيقية باستخدام نقطة [Process Try](/ar/api-reference/endpoint/monitors/process_try). يجلب هذا إشارات فعلية ويسلّمها إلى webhook الخاص بك — استخدم `tried_at` بتاريخ ماضٍ قريب لضمان توفر البيانات:

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

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

***

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

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

<CodeGroup>
  ```bash cURL — كشف التوقيع theme={null}
  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
    }'
  ```
</CodeGroup>

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

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

***

## بنية حمولة Webhook

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

<Tabs>
  <Tab title="الإشارة أولًا (Signal First)">
    في وضع `signal_first`، تحتوي الحمولة على مصفوفة `signals` في المستوى الأعلى:

    ```json theme={null}
    {
      "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": [...],
          ...
        },
        ...
      ]
    }
    ```

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

  <Tab title="الشركة أولًا (Company First)">
    في وضع `company_first`، تحتوي الحمولة على مصفوفة `companies` في المستوى الأعلى ببيانات شركات مُثراة وإشارات متداخلة:

    ```json theme={null}
    {
      "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": "j.smith@acmecorp.com",
              ...
            },
            ...
          ],
          "emails": ["info@acmecorp.com", ...],
          "phones": ["+14155551234", ...],
          "contacts": [...],
          ...
        },
        ...
      ]
    }
    ```

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

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

***

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

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

```json theme={null}
{
  "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"
  }
}
```

تستخدم مرشحات التوسع مفردات [البحث في التوسع](/ar/api-reference/endpoint/expansions/market_lookup)، لا مفردات الوظائف/الأخبار/الإعلانات — `froms` و`tos` للممر، بالإضافة إلى `stages` و`scopes` و`momentum` و`freshness` و`signal_types` و`signal_subtypes` و`signal_strengths` و`source_types` و`window_days`. احصل على الأسماء القياسية الصالحة من [مرجع التوسع](/ar/api-reference/endpoint/expansions/types).

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

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

```json theme={null}
{
  "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": [...]
    }
  ]
}
```

توجد معاني كل حقل على حدة في [مرجع حقول التوسع](/ar/knowledge-base/concepts/expansion-field-reference). ولسحب نفس الصفوف عند الطلب بدلًا من انتظار التفعيل، استخدم [البحث في إشارات التوسع](/ar/api-reference/endpoint/expansions/signal_search).

***

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

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

```json theme={null}
{
  "destination_type": "email",
  "destination_config": {
    "email": "alerts@your-company.com"
  }
}
```

<Info>
  يدعم Pubrio تسليم بريد إلكتروني بعلامة بيضاء للوكالات والفرق. [تواصل معنا](https://pubrio.com/en/get-in-touch) لمعرفة المزيد عن تخصيص نطاق المرسل والهوية البصرية.
</Info>

***

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

<AccordionGroup>
  <Accordion title="Webhook لا يستقبل حمولات">
    * تحقق من أن نقطتك الطرفية متاحة للعموم (وليست خلف جدار حماية أو VPN)
    * تأكد من أنها تُعيد رمز حالة `200` — أي رموز أخرى تُعامَل كإخفاق
    * استخدم نقطة [التحقق من صحة Webhook](/ar/api-reference/endpoint/monitors/webhook_validate) لاختبار الاتصال
    * راجع [سجلات الإحصاءات](/ar/api-reference/endpoint/monitors/statistics_logs) لرسائل الخطأ ورموز الاستجابة
  </Accordion>

  <Accordion title="تم إيقاف Monitor مؤقتًا بعد إخفاقات">
    إن كان webhook الخاص بك يُعيد رموزًا غير 200 باستمرار، يتوقف Monitor مؤقتًا بعد بلوغ `max_failure_trigger` من الإخفاقات المتتالية. أصلِح المشكلة وأعِد التفعيل عبر [تحديث Monitor](/ar/api-reference/endpoint/monitors/update).
  </Accordion>

  <Accordion title="حمولات مكررة">
    إن أخفق تسليم وكانت إعادة المحاولة مضبوطة، فقد تصلك نفس الحمولة عدة مرات. استخدم `triggered_at` أو معرّف السجل لإزالة التكرار من جهتك.
  </Accordion>

  <Accordion title="الحمولة كبيرة جدًا">
    قلّل `max_records_per_trigger` للحد من عدد السجلات لكل تسليم. يمكنك أيضًا تضييق مرشحاتك لتقليل حجم الإشارات المطابقة.
  </Accordion>
</AccordionGroup>