> 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/ru/docs/watchlist

# Список наблюдения доменов

DomScan API для анализа доменов: Мониторьте домены на предмет изменений истечения и доступности.

Мониторьте домены на предмет изменений истечения и доступности. Получайте оповещения, когда зарегистрированные домены становятся доступными.

Сколько доменов можно отслеживать, зависит от вашего тарифа. Бесплатные аккаунты могут отслеживать 5 доменов. Платные аккаунты могут отслеживать один домен на каждые 30 кредитов месячного тарифа, чего достаточно для ежедневной проверки каждого домена, минимум 100 и максимум 1000. Платные аккаунты без месячного тарифа могут отслеживать 100 доменов. GET /v1/watchlist возвращает ваш текущий лимит в поле max_domains. Добавление сверх лимита, дубликат или недопустимые данные отклоняются и не списывают кредиты.

**Мониторинг**

Войдите с помощью Google для доступа к вашему персонализированному списку наблюдения за доменами с оповещениями по электронной почте, веб-крючками и многим другим.

Получайте уведомления по электронной почте, Telegram, Slack, Discord или Webhook.

[Мониторинг](https://domscan.net/ru/monitor)
[Настройки](https://domscan.net/ru/monitor/settings)
[Мониторинг бренда](https://domscan.net/ru/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

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 |

### Вебхуки оповещений

Получайте оповещения мониторинга в виде подписанных JSON-запросов POST на собственные конечные точки 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/ru/webhook-alerts-api)

#### Стоимость

Каждое оповещение, доставленное на конечную точку с ответом 2xx, стоит кредитов: 2. Кредиты резервируются непосредственно перед первой попыткой и возвращаются, если доставка не удалась, отменена или конечная точка удалена. Тестовые события бесплатны. Если баланса не хватает, оповещение пропускается и ничего не списывается.

POST /v1/webhooks

Зарегистрируйте конечную точку HTTPS. URL должен разрешаться в публичный адрес. Опустите 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 или доменом бренда, а вы выбираете, какие из её событий получать. События отправляются на ваши подписанные конечные точки вебхуков и в оповещения в приложении.

| Тип | События | Когда срабатывает |
| --- | --- | --- |
| `ssl` | `ssl.expiring`, `ssl.expired`, `ssl.changed` | ssl.expiring, когда сертификат, который использует имя хоста, истекает в пределах ssl_expiring_days (30, 14, 7 или 1, по умолчанию 14), один раз на сертификат и порог. ssl.expired один раз на каждый истёкший сертификат. ssl.changed, когда новый отпечаток сертификата виден в двух проверках подряд; в payload указано, сменился ли издатель. |
| `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 минут после первого обнаружения изменения), цены каждые 2 часа относительно ежедневного снимка, а похожие домены партиями по 30 с полным проходом каждый день. После проверки с неизвестным результатом следующая попытка выполняется раньше. Подписки на бренды проверяются раз в сутки, а подтверждающая проверка выполняется через 90 минут после первого обнаружения изменения.

Создание подписок и выполнение проверок бесплатно. Каждое оповещение, доставленное на конечную точку вебхука с ответом 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 | Оповещать, когда цена в USD достигает этой суммы или опускается ниже. Для ценовой подписки нужен drop_percent, target_price или оба параметра. |
| record_types | string[] | Типы записей для отслеживания при dns. По умолчанию A, AAAA, MX, NS, TXT и CNAME. |
| notify_email | string | Необязательно. Дополнительно отправляет каждое оповещение этой подписки по электронной почте на этот адрес (3 кредита за каждое отправленное письмо). Доставка через вебхук не меняется. Измените адрес позже с помощью 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"
  }
}
```
