> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/ar/docs/watchlist

# قائمة مراقبة النطاق

باستخدام DomScan API، مراقبة النطاقات لانتهاء الصلاحية والتغييرات في التوفر. احصل على تنبيهات عند أن تصبح النطاقات المسجلة متاحة.

مراقبة النطاقات لانتهاء الصلاحية والتغييرات في التوفر. احصل على تنبيهات عند أن تصبح النطاقات المسجلة متاحة.

يعتمد عدد النطاقات التي يمكنك مراقبتها على خطتك. يمكن للحسابات المجانية مراقبة 5 نطاقات. يمكن للحسابات المدفوعة مراقبة نطاق واحد مقابل كل 30 رصيداً من رصيد الخطة الشهرية، وهو يكفي لفحص يومي لكل نطاق، بحد أدنى 100 وحد أقصى 1000. يمكن للحسابات المدفوعة بدون خطة شهرية مراقبة 100 نطاق. يعيد GET /v1/watchlist حدك الحالي في الحقل max_domains. تُرفض الإضافة التي تتجاوز الحد، أو المكررة، أو المدخلات غير الصالحة، ولا تكلّف أي رصيد.

**المراقبة**

سجّل الدخول باستخدام Google للوصول إلى قائمة مراقبة نطاقاتك الشخصية مع تنبيهات البريد الإلكتروني وwebhooks وغير ذلك.

تلقي الإشعارات عبر البريد الإلكتروني أو Telegram أو Slack أو Discord أو Webhook.

[المراقبة](https://domscan.net/ar/monitor)
[الإعدادات](https://domscan.net/ar/monitor/settings)
[مراقب العلامة التجارية](https://domscan.net/ar/brand-monitor-api)

GET /v1/watchlist

احصل على جميع النطاقات في قائمة المراقبة الخاصة بك.

#### مثال الرد

```json
{
                "watchlist": [
                {
                "domain": "startup.com",
                "added_at": "2024-01-15T10:30:00Z",
                "status": "registered",
                "expiry_date": "2025-01-15T00:00:00Z",
                "days_until_expiry": 287,
                "last_checked": "2024-03-01T12:00:00Z",
                "notify_email": "alerts@example.com",
                "check_count": 4
                }
                ],
                "total": 1,
                "max_domains": 333,
                "limit_basis": "monthly_credits",
                "updated_at": "2024-03-01T12:00:00Z"
                }
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `watchlist[]` | object[] |
| `watchlist[]` | object |
| `watchlist[].domain` | string |
| `watchlist[].added_at` | string |
| `watchlist[].status` | string |
| `watchlist[].last_checked` | string |
| `watchlist[].expiry_date` | string |
| `watchlist[].days_until_expiry` | integer |
| `watchlist[].notify_email` | string |
| `watchlist[].check_count` | integer |
| `total` | integer |
| `max_domains` | integer |
| `limit_basis` | string |
| `updated_at` | string |

POST /v1/watchlist

أضف نطاقاً إلى قائمة المراقبة الخاصة بك.

#### نص الطلب

```json
{
                "domain": "mydomain.com",
                "notify_email": "alerts@example.com"
                }
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `success` | boolean |
| `message` | string |
| `watchlist[]` | object[] |
| `watchlist[]` | object |
| `watchlist[].domain` | string |
| `watchlist[].added_at` | string |
| `watchlist[].status` | string |
| `watchlist[].last_checked` | string |
| `watchlist[].expiry_date` | string |
| `watchlist[].days_until_expiry` | integer |
| `watchlist[].notify_email` | string |
| `watchlist[].check_count` | integer |
| `total` | integer |
| `max_domains` | integer |
| `limit_basis` | string |

#### مثال الرد

```json
{
  "success": true,
  "message": "Added example.org to watchlist",
  "watchlist": [
    {
      "domain": "example.com",
      "added_at": "2026-06-02T09:12:00.000Z",
      "last_checked": "2026-10-09T03:00:12.000Z",
      "status": "expiring_soon",
      "expiry_date": "2026-12-18T14:22:08Z",
      "days_until_expiry": 70,
      "notify_email": "alerts@example.com"
    },
    {
      "domain": "example.org",
      "added_at": "2026-10-09T10:15:30.000Z",
      "status": "unknown",
      "notify_email": "alerts@example.com"
    }
  ],
  "total": 2,
  "max_domains": 333,
  "limit_basis": "monthly_credits"
}
```

PATCH /v1/watchlist/:domain

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

#### نص الطلب

```json
{
                "notify_email": "ops@example.com"
                }
```

```bash
curl -X PATCH -H "X-API-Key: your-api-key" -H "Content-Type: application/json"                 -d '{"notify_email":"ops@example.com"}' "https://domscan.net/v1/watchlist/mydomain.com"
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `success` | boolean |
| `message` | string |
| `domain` | object |
| `domain.domain` | string |
| `domain.added_at` | string |
| `domain.status` | string |
| `domain.last_checked` | string |
| `domain.expiry_date` | string |
| `domain.days_until_expiry` | integer |
| `domain.notify_email` | string |
| `domain.check_count` | integer |

#### مثال الرد

```json
{
  "success": true,
  "message": "Updated example.com in your watchlist",
  "domain": {
    "domain": "example.com",
    "added_at": "2026-06-02T09:12:00.000Z",
    "status": "registered",
    "notify_email": "ops@example.com",
    "check_count": 12
  }
}
```

DELETE /v1/watchlist?domain=mydomain.com

إزالة من قائمة المراقبة

```bash
curl -X DELETE -H "X-API-Key: your-api-key" "https://domscan.net/v1/watchlist?domain=mydomain.com"
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `success` | boolean |
| `message` | string |
| `domain` | string |
| `watchlist[]` | object[] |
| `watchlist[]` | object |
| `watchlist[].domain` | string |
| `watchlist[].added_at` | string |
| `watchlist[].status` | string |
| `watchlist[].last_checked` | string |
| `watchlist[].expiry_date` | string |
| `watchlist[].days_until_expiry` | integer |
| `watchlist[].notify_email` | string |
| `watchlist[].check_count` | integer |
| `total` | integer |

#### مثال الرد

```json
{
  "success": true,
  "message": "Request completed",
  "domain": "example.com",
  "watchlist": [
    {
      "domain": "example.com",
      "added_at": "2026-08-27T12:00:00Z",
      "status": "registered",
      "last_checked": "2026-08-27T12:00:00Z",
      "expiry_date": "2026-08-27T12:00:00Z",
      "days_until_expiry": 1,
      "notify_email": "user@example.com",
      "check_count": 1
    }
  ],
  "total": 1
}
```

GET /v1/watchlist/expiring?days=30

تنتهي قريباً

#### مثال الرد

```json
{
                "expiring_domains": [
                {
                "domain": "renewal-window.com",
                "status": "expiring_soon",
                "expiry_date": "2026-05-12T00:00:00Z",
                "days_until_expiry": 28,
                "check_count": 11
                }
                ],
                "total": 1,
                "threshold_days": 30
                }
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `expiring_domains[]` | object[] |
| `expiring_domains[]` | object |
| `expiring_domains[].domain` | string |
| `expiring_domains[].added_at` | string |
| `expiring_domains[].status` | string |
| `expiring_domains[].last_checked` | string |
| `expiring_domains[].expiry_date` | string |
| `expiring_domains[].days_until_expiry` | integer |
| `expiring_domains[].notify_email` | string |
| `expiring_domains[].check_count` | integer |
| `total` | integer |
| `threshold_days` | integer |

GET /v1/watchlist/available

متاح

يدعم ترقيم الصفحات: أرسل `limit` (من 1 إلى 100) ومرّر `next_cursor` مرة أخرى بوصفه `cursor`. تتضمن الاستجابات `has_more` و`next_cursor`. وإذا لم تُرسل `limit` تُرجع القائمة كاملة. راجع [ترقيم الصفحات](https://domscan.net/docs/response-format#pagination).

#### مثال الرد

```json
{
                "available_domains": [
                {
                "domain": "startupdrop.ai",
                "status": "available",
                "last_checked": "2026-04-14T08:30:00Z",
                "check_count": 18
                }
                ],
                "total": 1,
                "message": "هذه النطاقات من قائمة المراقبة الخاصة بك متاحة الآن للتسجيل!"
                }
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `available_domains[]` | object[] |
| `available_domains[]` | object |
| `available_domains[].domain` | string |
| `available_domains[].added_at` | string |
| `available_domains[].status` | string |
| `available_domains[].last_checked` | string |
| `available_domains[].expiry_date` | string |
| `available_domains[].days_until_expiry` | integer |
| `available_domains[].notify_email` | string |
| `available_domains[].check_count` | integer |
| `total` | integer |
| `message` | string |

### خطافات ويب التنبيهات

استقبل تنبيهات المراقبة على شكل طلبات POST موقّعة بصيغة JSON إلى نقاط نهاية HTTPS الخاصة بك. أدر نقاط النهاية بمفتاح API، أو من إعدادات المراقبة أثناء تسجيل الدخول.

#### أنواع الأحداث

| المراقبة | الأحداث |
| --- | --- |
| توفر عناصر قائمة المراقبة وانتهاؤها وحالتها | `domain.available`, `domain.expiring_30`, `domain.expiring_14`, `domain.expiring_7`, `domain.expiring_1`, `domain.status_change` |
| مراقبة تغيّر النطاقات | `domain.dns_changed`, `domain.certificate_changed`, `domain.registration_changed`, `domain.hosting_changed`, `domain.technology_changed`, `domain.email_security_changed` |
| مراقبة العلامة التجارية (تسجيلات جديدة لنطاقات مشابهة) | `brand.threat_detected` |
| اشتراكات تنبيهات قائمة المراقبة (الشهادات والأسعار وسجلات DNS والنطاقات المشابهة) | `ssl.expiring`, `ssl.expired`, `ssl.changed`, `price.dropped`, `dns.changed`, `typosquat.detected` |
| تنبيهات تغيير العلامة التجارية (الشعارات والألوان والاسم والحسابات الاجتماعية) | `brand.updated` |
| المهام غير المتزامنة (مجانية، فقط للمهام المنشأة مع notify_webhook) | `job.completed`, `job.failed`, `job.cancelled` |
| حدث اختبار (مجاني) | `webhook.test` |

[اقرأ دليل واجهة API لتنبيهات خطاف الويب](https://domscan.net/ar/webhook-alerts-api)

#### الأسعار

يكلّف كل تنبيه يُسلَّم إلى نقطة نهاية برد 2xx ما مقداره 2 رصيد. تُحجز الأرصدة قبل المحاولة الأولى مباشرة، وتُسترد إذا فشل التسليم أو أُلغي أو حُذفت نقطة النهاية. أحداث الاختبار مجانية. وعندما يكون الرصيد غير كافٍ يُتخطى التنبيه ولا يُخصم شيء.

POST /v1/webhooks

سجّل نقطة نهاية HTTPS. يجب أن يُحل العنوان إلى عنوان عام. احذف events أو مرّر ["*"] لاستقبال كل أنواع الأحداث. لا يُعاد سر التوقيع إلا في هذا الرد.

#### طلب مثال

```bash
curl -X POST "https://domscan.net/v1/webhooks" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/domscan",
    "events": ["domain.expiring_30", "domain.available", "domain.dns_changed"]
  }'
```

#### مثال الرد

```json
{
  "endpoint": {
    "id": "whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3",
    "url": "https://hooks.example.com/domscan",
    "events": ["domain.available", "domain.expiring_30", "domain.dns_changed"],
    "status": "active",
    "secret_hint": "9c2e"
  },
  "secret": "whsec_..."
}
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `endpoint` | object |
| `endpoint.id` | string |
| `endpoint.url` | string |
| `endpoint.description` | string \| null |
| `endpoint.events[]` | string[] |
| `endpoint.status` | string |
| `endpoint.disabled_reason` | string \| null |
| `endpoint.consecutive_failures` | integer |
| `endpoint.secret_hint` | string |
| `endpoint.previous_secret_expires_at` | string \| null |
| `endpoint.secret_rotated_at` | string \| null |
| `endpoint.last_success_at` | string \| null |
| `endpoint.last_failure_at` | string \| null |
| `endpoint.last_error` | string \| null |
| `endpoint.created_at` | string |
| `endpoint.updated_at` | string |
| `endpoint.disabled_at` | string \| null |
| `secret` | string |

GET /v1/webhooks

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

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `endpoints[]` | object[] |
| `endpoints[]` | object |
| `endpoints[].id` | string |
| `endpoints[].url` | string |
| `endpoints[].description` | string \| null |
| `endpoints[].events[]` | string[] |
| `endpoints[].status` | string |
| `endpoints[].disabled_reason` | string \| null |
| `endpoints[].consecutive_failures` | integer |
| `endpoints[].secret_hint` | string |
| `endpoints[].previous_secret_expires_at` | string \| null |
| `endpoints[].secret_rotated_at` | string \| null |
| `endpoints[].last_success_at` | string \| null |
| `endpoints[].last_failure_at` | string \| null |
| `endpoints[].last_error` | string \| null |
| `endpoints[].created_at` | string |
| `endpoints[].updated_at` | string |
| `endpoints[].disabled_at` | string \| null |
| `available_events[]` | string[] |
| `all_events` | string |
| `test_event` | string |
| `policy` | object |
| `policy.secret_rotation_grace_seconds` | integer |
| `policy.secret_rotation_credits` | integer |
| `policy.credits_per_delivered_alert` | integer |
| `policy.test_event_credits` | integer |
| `policy.job_event_credits` | integer |
| `policy.failed_deliveries_charged` | boolean |
| `policy.max_endpoints` | integer |
| `policy.max_attempts` | integer |
| `policy.disable_after_consecutive_failures` | integer |
| `policy.signature_tolerance_seconds` | integer |

#### مثال الرد

```json
{
  "endpoints": [
    {
      "id": "example-id",
      "url": "https://example.com",
      "events": [
        "example"
      ],
      "status": "active",
      "secret_hint": "example",
      "created_at": "2026-08-27T12:00:00Z",
      "description": "example",
      "disabled_reason": "customer",
      "consecutive_failures": 1,
      "previous_secret_expires_at": "2026-08-27T12:00:00Z",
      "secret_rotated_at": "2026-08-27T12:00:00Z",
      "last_success_at": "2026-08-27T12:00:00Z",
      "last_failure_at": "2026-08-27T12:00:00Z",
      "last_error": "example",
      "updated_at": "2026-08-27T12:00:00Z",
      "disabled_at": "2026-08-27T12:00:00Z"
    }
  ],
  "available_events": [
    "domain.available"
  ],
  "policy": {
    "credits_per_delivered_alert": 2,
    "test_event_credits": 0,
    "failed_deliveries_charged": false,
    "max_endpoints": 1,
    "max_attempts": 1,
    "disable_after_consecutive_failures": 1,
    "signature_tolerance_seconds": 1,
    "secret_rotation_grace_seconds": 86400,
    "secret_rotation_credits": 0,
    "job_event_credits": 0
  },
  "all_events": "*",
  "test_event": "webhook.test"
}
```

PATCH /v1/webhooks/:webhook_id

أوقف نقطة نهاية مؤقتًا أو فعّلها، أو غيّر أحداثها أو عدّل وصفها. يؤدي تفعيل نقطة النهاية إلى تصفير عدد الإخفاقات.

```json
{ "enabled": true, "events": ["*"] }
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `endpoint` | object |
| `endpoint.id` | string |
| `endpoint.url` | string |
| `endpoint.description` | string \| null |
| `endpoint.events[]` | string[] |
| `endpoint.status` | string |
| `endpoint.disabled_reason` | string \| null |
| `endpoint.consecutive_failures` | integer |
| `endpoint.secret_hint` | string |
| `endpoint.previous_secret_expires_at` | string \| null |
| `endpoint.secret_rotated_at` | string \| null |
| `endpoint.last_success_at` | string \| null |
| `endpoint.last_failure_at` | string \| null |
| `endpoint.last_error` | string \| null |
| `endpoint.created_at` | string |
| `endpoint.updated_at` | string |
| `endpoint.disabled_at` | string \| null |

#### مثال الرد

```json
{
  "endpoint": {
    "id": "example-id",
    "url": "https://example.com",
    "events": [
      "example"
    ],
    "status": "active",
    "secret_hint": "example",
    "created_at": "2026-08-27T12:00:00Z",
    "description": "example",
    "disabled_reason": "customer",
    "consecutive_failures": 1,
    "previous_secret_expires_at": "2026-08-27T12:00:00Z",
    "secret_rotated_at": "2026-08-27T12:00:00Z",
    "last_success_at": "2026-08-27T12:00:00Z",
    "last_failure_at": "2026-08-27T12:00:00Z",
    "last_error": "example",
    "updated_at": "2026-08-27T12:00:00Z",
    "disabled_at": "2026-08-27T12:00:00Z"
  }
}
```

DELETE /v1/webhooks/:webhook_id

احذف نقطة نهاية. تُلغى عمليات التسليم المعلقة وتُسترد أي أرصدة محجوزة.

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `id` | string |
| `deleted` | boolean |

#### مثال الرد

```json
{
  "id": "example-id",
  "deleted": true
}
```

POST /v1/webhooks/:webhook_id/test

أرسل حدث webhook.test واحدًا مجانًا وأعد النتيجة. لا تُعاد محاولة أحداث الاختبار ولا تُحتسب ضمن الإيقاف المؤقت التلقائي.

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `delivery` | object |
| `delivery.id` | string |
| `delivery.endpoint_id` | string |
| `delivery.event_id` | string |
| `delivery.event_type` | string |
| `delivery.status` | string |
| `delivery.attempts` | integer |
| `delivery.next_attempt_at` | string \| null |
| `delivery.last_attempt_at` | string \| null |
| `delivery.response_status` | integer \| null |
| `delivery.last_error` | string \| null |
| `delivery.credits_charged` | integer |
| `delivery.refunded` | boolean |
| `delivery.created_at` | string |
| `delivery.delivered_at` | string \| null |
| `delivered` | boolean |

#### مثال الرد

```json
{
  "delivery": {
    "id": "example-id",
    "endpoint_id": "example",
    "event_id": "example",
    "event_type": "domain",
    "status": "pending",
    "attempts": 1,
    "next_attempt_at": "2026-08-27T12:00:00Z",
    "last_attempt_at": "2026-08-27T12:00:00Z",
    "response_status": 1,
    "last_error": "example",
    "credits_charged": 1,
    "refunded": false,
    "created_at": "2026-08-27T12:00:00Z",
    "delivered_at": "2026-08-27T12:00:00Z"
  },
  "delivered": false
}
```

POST /v1/webhooks/:webhook_id/rotate-secret

استبدل سر التوقيع لنقطة نهاية، بما في ذلك نقطة نهاية موقوفة مؤقتًا. يُعاد السر الجديد في هذه الاستجابة فقط. خلال الـ 24 ساعة التالية يُوقَّع كل تسليم بالسر الجديد والسر السابق معًا. التدوير مجاني.

#### طلب مثال

```bash
curl -X POST "https://domscan.net/v1/webhooks/whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3/rotate-secret" \
  -H "X-API-Key: $DOMSCAN_API_KEY"
```

#### مثال الرد

```json
{
  "endpoint": {
    "id": "whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3",
    "status": "active",
    "secret_hint": "4b7a",
    "previous_secret_expires_at": "2026-10-11T12:00:00.000Z"
  },
  "secret": "whsec_...",
  "previous_secret_expires_at": "2026-10-11T12:00:00.000Z",
  "grace_period_seconds": 86400
}
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `endpoint` | object |
| `endpoint.id` | string |
| `endpoint.url` | string |
| `endpoint.description` | string \| null |
| `endpoint.events[]` | string[] |
| `endpoint.status` | string |
| `endpoint.disabled_reason` | string \| null |
| `endpoint.consecutive_failures` | integer |
| `endpoint.secret_hint` | string |
| `endpoint.previous_secret_expires_at` | string \| null |
| `endpoint.secret_rotated_at` | string \| null |
| `endpoint.last_success_at` | string \| null |
| `endpoint.last_failure_at` | string \| null |
| `endpoint.last_error` | string \| null |
| `endpoint.created_at` | string |
| `endpoint.updated_at` | string |
| `endpoint.disabled_at` | string \| null |
| `secret` | string |
| `previous_secret_expires_at` | string |
| `grace_period_seconds` | integer |

GET /v1/webhooks/:webhook_id/deliveries

#### معاملات الاستعلام

| المعامل | النوع | Description |
| --- | --- | --- |
| limit | integer | عدد عمليات التسليم المراد إعادتها، من 1 إلى 100. القيمة الافتراضية 50. |

اعرض عمليات التسليم الأخيرة مع حالتها وعدد المحاولات ورد HTTP والأرصدة المخصومة والمبالغ المستردة. تُحفظ سجلات التسليم لمدة 30 يومًا.

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `endpoint_id` | string |
| `deliveries[]` | object[] |
| `deliveries[]` | object |
| `deliveries[].id` | string |
| `deliveries[].endpoint_id` | string |
| `deliveries[].event_id` | string |
| `deliveries[].event_type` | string |
| `deliveries[].status` | string |
| `deliveries[].attempts` | integer |
| `deliveries[].next_attempt_at` | string \| null |
| `deliveries[].last_attempt_at` | string \| null |
| `deliveries[].response_status` | integer \| null |
| `deliveries[].last_error` | string \| null |
| `deliveries[].credits_charged` | integer |
| `deliveries[].refunded` | boolean |
| `deliveries[].created_at` | string |
| `deliveries[].delivered_at` | string \| null |

#### مثال الرد

```json
{
  "endpoint_id": "example",
  "deliveries": [
    {
      "id": "example-id",
      "endpoint_id": "example",
      "event_id": "example",
      "event_type": "domain",
      "status": "pending",
      "attempts": 1,
      "next_attempt_at": "2026-08-27T12:00:00Z",
      "last_attempt_at": "2026-08-27T12:00:00Z",
      "response_status": 1,
      "last_error": "example",
      "credits_charged": 1,
      "refunded": false,
      "created_at": "2026-08-27T12:00:00Z",
      "delivered_at": "2026-08-27T12:00:00Z"
    }
  ]
}
```

#### تنسيق الطلب

كل تنبيه هو طلب POST بنص JSON. يبقى الحقل id ثابتًا للحدث الواحد ويتكرر في X-DomScan-Event-Id، فيمكنك تجاهل المحاولات المعادة التي عالجتها سابقًا.

```http
POST /domscan HTTP/1.1
Content-Type: application/json
X-DomScan-Event: domain.expiring_30
X-DomScan-Event-Id: evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9
X-DomScan-Timestamp: 1791633600
X-DomScan-Signature: sha256=...

{
  "id": "evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9",
  "type": "domain.expiring_30",
  "created": "2026-10-10T12:00:00.000Z",
  "data": {
    "domain": "acme.io",
    "previous_status": "registered",
    "current_status": "expiring_soon",
    "expiry_date": "2026-11-09T00:00:00Z",
    "days_until_expiry": 30,
    "checked_at": "2026-10-10T12:00:00.000Z"
  }
}
```

#### التحقق من التوقيعات

احسب HMAC-SHA256 لقيمة X-DomScan-Timestamp متبوعة بنقطة ثم نص الطلب الخام، مستخدمًا سر نقطة النهاية. قارن النتيجة بالقيمة في X-DomScan-Signature بمقارنة ثابتة الزمن، وارفض الطلبات التي يزيد عمر طابعها الزمني على 5 دقيقة.

يتحقق المثال أدناه من كل توقيع في الترويسة، لذا يستمر عمله أثناء تدوير السر.

```javascript
import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before JSON parsing.
function verifyDomScanWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-domscan-timestamp'];
  const header = headers['x-domscan-signature'] || '';
  if (!/^\d{10}$/.test(timestamp || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = Buffer.from('sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex'));
  // One entry normally; two during a secret rotation (new secret first).
  return header.split(',').some((entry) => {
    const candidate = Buffer.from(entry.trim());
    return candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected);
  });
}
```

#### تدوير سر التوقيع

خلال فترة السماح البالغة 24 ساعة بعد التدوير، يحتوي X-DomScan-Signature على توقيعين مفصولين بفاصلة، ويأتي توقيع السر الجديد أولًا كما يظهر أدناه. اقبل الطلب إذا طابق أي توقيع سرًا تثق به، ثم انشر السر الجديد وبعدها أوقف الوثوق بالسر القديم. إذا دوّرت مرة أخرى خلال فترة السماح، يُلغى السر السابق الأقدم فورًا.

```http
X-DomScan-Signature: sha256=<new>,sha256=<previous>
```

#### إعادة المحاولة والإيقاف المؤقت التلقائي

أعد أي حالة 2xx خلال 8 ثوانٍ لتأكيد استلام التنبيه. تُعاد محاولة عمليات إعادة التوجيه وحالات الرد الأخرى وانتهاء المهلة بتراجع أسي (1 و4 و16 و64 و256 دقيقة)، بحد أقصى 6 محاولة إجمالًا. بعد 15 محاولة فاشلة متتالية تُوقَف نقطة النهاية مؤقتًا؛ فعّلها من جديد باستخدام PATCH أو من إعدادات المراقبة.

عند إيقاف نقطة نهاية مؤقتًا بسبب إخفاقات متكررة، يتلقى مالكها رسالة بريد إلكتروني واحدة تتضمن مضيف نقطة النهاية وآخر خطأ ورابطًا إلى إعدادات المراقبة. أصلح نقطة النهاية ثم فعّلها من جديد من إعدادات المراقبة أو عبر PATCH مع ضبط enabled على true. يعيد التفعيل عدد الإخفاقات إلى الصفر.

### اشتراكات تنبيهات قائمة المراقبة

اشترك في التنبيهات التي تريدها لأي عنصر في قائمة المراقبة. يراقب كل اشتراك اسم مضيف أو TLD أو نطاق علامة تجارية واحدًا، وتختار أنت الأحداث التي تريد استلامها. تُرسل الأحداث إلى نقاط Webhook الموقّعة الخاصة بك وإلى التنبيهات داخل التطبيق.

| النوع | الأحداث | متى يُطلق |
| --- | --- | --- |
| `ssl` | `ssl.expiring`, `ssl.expired`, `ssl.changed` | يُطلق ssl.expiring عندما تنتهي صلاحية الشهادة التي يقدمها اسم المضيف خلال ssl_expiring_days (30 أو 14 أو 7 أو 1، والافتراضي 14)، مرة واحدة لكل شهادة وكل حد. يُطلق ssl.expired مرة واحدة لكل شهادة منتهية الصلاحية. يُطلق ssl.changed عند رصد بصمة شهادة جديدة في فحصين متتاليين، وتوضح الحمولة ما إذا كانت الجهة المُصدِرة قد تغيّرت. |
| `price` | `price.dropped` | عندما ينخفض سعر التسجيل أو التجديد لـ TLD، لدى مسجّل محدد أو لدى الأرخص، بما لا يقل عن drop_percent عن أعلى سعر منذ آخر تنبيه، أو يصل إلى target_price أو أقل. تأتي الأسعار من لقطة التسعير اليومية، وتُقيَّم كل لقطة مرة واحدة. |
| `dns` | `dns.changed` | عندما يعيد نوع سجل مراقَب (A أو AAAA أو MX أو NS أو TXT أو CNAME) لأي اسم مضيف الإجابة الجديدة نفسها في عمليتي بحث متتاليتين مؤكدتين. |
| `typosquat` | `typosquat.detected` | عندما يُسجَّل نطاق مشابه لنطاق العلامة التجارية حديثًا ويتأكد ذلك عبر بحث تسجيل موثوق. المسح الكامل الأول للنطاقات المشابهة يحدد خط الأساس ولا يرسل تنبيهًا. |
| `brand` | `brand.updated` | عندما يتغير الشعار المربع أو الشعار العريض أو الألوان أو الاسم أو الحسابات الاجتماعية المعلنة لنطاق علامة تجارية، ويظهر التغيير مجددًا في الفحص التالي. اختر ما تريد مراقبته عبر attributes (logo وwide_logo وcolors وname وsocials؛ الكل افتراضيًا). يحدد الفحص الأول خط الأساس ولا يُرسل تنبيهًا، وتبقى أي سمة تعذّر فحصها دون تغيير. |

الأدلة الدقيقة وحدها تطلق حدثًا. فشل مصافحة TLS، وبحث DNS الذي يفشل أو تنتهي مهلته، والسعر المفقود، والبحث المحظور أو المحدود المعدل كلها حالات غير معروفة: لا تغيّر شيئًا ولا تُرسل تنبيهًا ولا تُحتسب أي رسوم. أول فحص مؤكد للاشتراك يحدد خط الأساس الخاص به.

تعمل الفحوصات تلقائيًا: الشهادات كل 12 ساعة، وسجلات DNS كل ساعة (مع فحص تأكيدي بعد 15 دقيقة من رصد التغيير أول مرة)، والأسعار كل ساعتين بالمقارنة مع اللقطة اليومية، والنطاقات المشابهة على دفعات من 30 مع مسح كامل كل يوم. بعد فحص غير معروف يأتي المحاولة التالية أبكر. تُفحص اشتراكات العلامات التجارية مرة واحدة يوميًا، مع فحص تأكيدي بعد 90 دقيقة من رصد التغيير لأول مرة.

إنشاء الاشتراكات وتشغيل الفحوصات مجاني. كل تنبيه يُسلَّم إلى نقطة Webhook باستجابة 2xx يكلّف 2 رصيدًا، مثل أي تنبيه مراقبة آخر. تُسترد رسوم عمليات التسليم الفاشلة، ويمكن أن يضم الحساب ما يصل إلى 100 اشتراك، منها 20 للنطاقات المشابهة.

POST /v1/watchlist/alerts

أنشئ اشتراكًا. يحدد type الحقول المطبّقة: domain لـ ssl وdns وtyposquat، وtld وregistrar وprice_type وdrop_percent وtarget_price لـ price. تُرفض الحقول التي لا تنطبق على النوع.

#### نص الطلب

| المعامل | النوع | Description |
| --- | --- | --- |
| type | string | ssl أو price أو dns أو typosquat. مطلوب. |
| domain | string | اسم المضيف المراد مراقبته لـ ssl وdns، أو نطاق العلامة التجارية لـ typosquat. |
| tld | string | الـ TLD المراد مراقبته لـ price، مثل com. |
| registrar | string | معرّف المسجّل لـ price. احذفه لمراقبة أرخص مسجّل. |
| events | string[] | الأحداث المراد استلامها. الافتراضي هو كل أحداث النوع. |
| ssl_expiring_days | integer | عدد الأيام قبل الانتهاء لـ ssl.expiring: 30 أو 14 أو 7 أو 1. الافتراضي 14. |
| price_type | string | registration (الافتراضي) أو renewal. |
| drop_percent | number | أرسل تنبيهًا عند انخفاض لا تقل نسبته عن هذه النسبة المئوية، من 1 إلى 95. |
| target_price | number | أرسل تنبيهًا عندما يصل السعر بالدولار الأمريكي إلى هذا المبلغ أو أقل. يتطلب اشتراك السعر drop_percent أو target_price أو كليهما. |
| record_types | string[] | أنواع السجلات المراد مراقبتها لـ dns. الافتراضي A وAAAA وMX وNS وTXT وCNAME. |
| notify_email | string | اختياري. يرسل أيضاً كل تنبيه من هذا الاشتراك بالبريد الإلكتروني إلى هذا العنوان (3 أرصدة لكل بريد مرسل). لا يتغير التسليم عبر Webhook. غيّره لاحقاً باستخدام PATCH، أو أرسل null لإيقاف الرسائل. |

#### طلب مثال

```bash
curl -X POST "https://domscan.net/v1/watchlist/alerts" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "price",
    "tld": "com",
    "registrar": "porkbun",
    "price_type": "renewal",
    "drop_percent": 10,
    "target_price": 9.5
  }'
```

#### مثال الرد

```json
{
  "subscription": {
    "id": "mas_8c1f0e2d3b4a59687766554433221100",
    "type": "price",
    "target": "com",
    "registrar": "porkbun",
    "events": ["price.dropped"],
    "status": "active",
    "price_type": "renewal",
    "drop_percent": 10,
    "target_price": 9.5,
    "currency": "USD",
    "observed": null,
    "last_check_status": null,
    "next_check_at": "2026-10-10T12:00:00.000Z"
  }
}
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `subscription` | object |
| `subscription.id` | string |
| `subscription.type` | string |
| `subscription.target` | string |
| `subscription.registrar` | string \| null |
| `subscription.events[]` | string[] |
| `subscription.status` | string |
| `subscription.ssl_expiring_days` | integer \| null |
| `subscription.price_type` | string \| null |
| `subscription.drop_percent` | number \| null |
| `subscription.target_price` | number \| null |
| `subscription.currency` | string \| null |
| `subscription.record_types[]` | string[] |
| `subscription.attributes[]` | string[] |
| `subscription.notify_email` | string \| null |
| `subscription.observed` | object \| null |
| `subscription.last_check_at` | string \| null |
| `subscription.last_check_status` | string \| null |
| `subscription.last_error` | string \| null |
| `subscription.next_check_at` | string \| null |
| `subscription.created_at` | string |
| `subscription.updated_at` | string |

GET /v1/watchlist/alerts

اعرض اشتراكاتك مع أحدث دليل مؤكد وحالة الفحص، والأحداث التي يدعمها كل نوع، وجدول الفحص، وسعر التنبيه.

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `subscriptions[]` | object[] |
| `subscriptions[]` | object |
| `subscriptions[].id` | string |
| `subscriptions[].type` | string |
| `subscriptions[].target` | string |
| `subscriptions[].registrar` | string \| null |
| `subscriptions[].events[]` | string[] |
| `subscriptions[].status` | string |
| `subscriptions[].ssl_expiring_days` | integer \| null |
| `subscriptions[].price_type` | string \| null |
| `subscriptions[].drop_percent` | number \| null |
| `subscriptions[].target_price` | number \| null |
| `subscriptions[].currency` | string \| null |
| `subscriptions[].record_types[]` | string[] |
| `subscriptions[].attributes[]` | string[] |
| `subscriptions[].notify_email` | string \| null |
| `subscriptions[].observed` | object \| null |
| `subscriptions[].last_check_at` | string \| null |
| `subscriptions[].last_check_status` | string \| null |
| `subscriptions[].last_error` | string \| null |
| `subscriptions[].next_check_at` | string \| null |
| `subscriptions[].created_at` | string |
| `subscriptions[].updated_at` | string |
| `total` | integer |
| `available_types` | object |
| `available_types.ssl[]` | string[] |
| `available_types.price[]` | string[] |
| `available_types.dns[]` | string[] |
| `available_types.typosquat[]` | string[] |
| `available_types.brand[]` | string[] |
| `policy` | object |
| `policy.credits_per_delivered_alert` | integer |
| `policy.check_credits` | integer |
| `policy.unknown_checks_charged` | boolean |
| `policy.max_subscriptions` | integer |
| `policy.max_typosquat_subscriptions` | integer |
| `policy.max_brand_subscriptions` | integer |
| `policy.brand_attributes[]` | string[] |
| `policy.ssl_expiring_days[]` | integer[] |
| `policy.default_ssl_expiring_days` | integer |
| `policy.record_types[]` | string[] |
| `policy.price_types[]` | string[] |
| `policy.check_interval_minutes` | object |
| `policy.confirmation_checks` | object |

#### مثال الرد

```json
{
  "subscriptions": [
    {
      "id": "example-id",
      "type": "ssl",
      "target": "example",
      "registrar": "example",
      "events": [
        "ssl.expiring"
      ],
      "status": "active",
      "ssl_expiring_days": 30,
      "price_type": "registration",
      "drop_percent": 0.5,
      "target_price": 0.5,
      "currency": "USD",
      "record_types": [
        "A"
      ],
      "attributes": [
        "logo"
      ],
      "notify_email": "user@example.com",
      "observed": {},
      "last_check_at": "2026-08-27T12:00:00Z",
      "last_check_status": "baseline",
      "last_error": "example",
      "next_check_at": "2026-08-27T12:00:00Z",
      "created_at": "2026-08-27T12:00:00Z",
      "updated_at": "2026-08-27T12:00:00Z"
    }
  ],
  "total": 1,
  "available_types": {
    "ssl": [
      "ssl.expiring"
    ],
    "price": [
      "price.dropped"
    ],
    "dns": [
      "dns.changed"
    ],
    "typosquat": [
      "typosquat.detected"
    ],
    "brand": [
      "brand.updated"
    ]
  },
  "policy": {
    "credits_per_delivered_alert": 2,
    "check_credits": 0,
    "unknown_checks_charged": false,
    "max_subscriptions": 1,
    "check_interval_minutes": {},
    "max_typosquat_subscriptions": 1,
    "max_brand_subscriptions": 1,
    "brand_attributes": [
      "logo"
    ],
    "ssl_expiring_days": [
      1
    ],
    "default_ssl_expiring_days": 1,
    "record_types": [
      "A"
    ],
    "price_types": [
      "registration"
    ],
    "confirmation_checks": {}
  }
}
```

GET /v1/watchlist/alerts/:subscription_id

اجلب اشتراكًا واحدًا مع أحدث دليل مؤكد له وآخر 20 حدثًا.

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `subscription` | object |
| `subscription.id` | string |
| `subscription.type` | string |
| `subscription.target` | string |
| `subscription.registrar` | string \| null |
| `subscription.events[]` | string[] |
| `subscription.status` | string |
| `subscription.ssl_expiring_days` | integer \| null |
| `subscription.price_type` | string \| null |
| `subscription.drop_percent` | number \| null |
| `subscription.target_price` | number \| null |
| `subscription.currency` | string \| null |
| `subscription.record_types[]` | string[] |
| `subscription.attributes[]` | string[] |
| `subscription.notify_email` | string \| null |
| `subscription.observed` | object \| null |
| `subscription.last_check_at` | string \| null |
| `subscription.last_check_status` | string \| null |
| `subscription.last_error` | string \| null |
| `subscription.next_check_at` | string \| null |
| `subscription.created_at` | string |
| `subscription.updated_at` | string |
| `events[]` | object[] |
| `events[]` | object |
| `events[].id` | string |
| `events[].event_type` | string |
| `events[].detected_at` | string |
| `events[].published_at` | string \| null |
| `events[].data` | object |

#### مثال الرد

```json
{
  "subscription": {
    "id": "example-id",
    "type": "ssl",
    "target": "example",
    "registrar": "example",
    "events": [
      "ssl.expiring"
    ],
    "status": "active",
    "ssl_expiring_days": 30,
    "price_type": "registration",
    "drop_percent": 0.5,
    "target_price": 0.5,
    "currency": "USD",
    "record_types": [
      "A"
    ],
    "attributes": [
      "logo"
    ],
    "notify_email": "user@example.com",
    "observed": {},
    "last_check_at": "2026-08-27T12:00:00Z",
    "last_check_status": "baseline",
    "last_error": "example",
    "next_check_at": "2026-08-27T12:00:00Z",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z"
  },
  "events": [
    {
      "id": "example-id",
      "event_type": "ssl.expiring",
      "detected_at": "2026-08-27T12:00:00Z",
      "published_at": "2026-08-27T12:00:00Z",
      "data": {}
    }
  ]
}
```

PATCH /v1/watchlist/alerts/:subscription_id

أوقف اشتراكًا مؤقتًا أو استأنفه عبر enabled، أو غيّر events أو ssl_expiring_days أو drop_percent أو target_price أو record_types. لا يرسل السعر المستهدف الجديد تنبيهًا إلا عند حدوث تغيّر لاحق في السعر.

```json
{ "enabled": false }
```

```json
{ "notify_email": "security@example.com" }
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `subscription` | object |
| `subscription.id` | string |
| `subscription.type` | string |
| `subscription.target` | string |
| `subscription.registrar` | string \| null |
| `subscription.events[]` | string[] |
| `subscription.status` | string |
| `subscription.ssl_expiring_days` | integer \| null |
| `subscription.price_type` | string \| null |
| `subscription.drop_percent` | number \| null |
| `subscription.target_price` | number \| null |
| `subscription.currency` | string \| null |
| `subscription.record_types[]` | string[] |
| `subscription.attributes[]` | string[] |
| `subscription.notify_email` | string \| null |
| `subscription.observed` | object \| null |
| `subscription.last_check_at` | string \| null |
| `subscription.last_check_status` | string \| null |
| `subscription.last_error` | string \| null |
| `subscription.next_check_at` | string \| null |
| `subscription.created_at` | string |
| `subscription.updated_at` | string |

#### مثال الرد

```json
{
  "subscription": {
    "id": "example-id",
    "type": "ssl",
    "target": "example",
    "registrar": "example",
    "events": [
      "ssl.expiring"
    ],
    "status": "active",
    "ssl_expiring_days": 30,
    "price_type": "registration",
    "drop_percent": 0.5,
    "target_price": 0.5,
    "currency": "USD",
    "record_types": [
      "A"
    ],
    "attributes": [
      "logo"
    ],
    "notify_email": "user@example.com",
    "observed": {},
    "last_check_at": "2026-08-27T12:00:00Z",
    "last_check_status": "baseline",
    "last_error": "example",
    "next_check_at": "2026-08-27T12:00:00Z",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z"
  }
}
```

DELETE /v1/watchlist/alerts/:subscription_id

احذف اشتراكًا. تُسقَط الأحداث التي لم تُرسل بعد ولا تُحتسب عليها أي رسوم.

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `id` | string |
| `deleted` | boolean |

#### مثال الرد

```json
{
  "id": "example-id",
  "deleted": true
}
```

#### مثال على حدث dns.changed

```json
{
  "id": "evt_2b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e",
  "type": "dns.changed",
  "created": "2026-10-10T12:15:00.000Z",
  "data": {
    "domain": "partner-shop.example",
    "changes": [
      {
        "record_type": "MX",
        "before": ["10 mx1.mail.example"],
        "after": ["10 mx.other-mail.example"],
        "added": ["10 mx.other-mail.example"],
        "removed": ["10 mx1.mail.example"],
        "first_seen_at": "2026-10-10T12:00:00.000Z"
      }
    ],
    "confirmed_checks": 2,
    "confirmed_at": "2026-10-10T12:15:00.000Z",
    "subscription_id": "mas_8c1f0e2d3b4a59687766554433221100"
  }
}
```
