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

# Lista obserwacyjna domen

DomScan API do analizy domen: Monitoruj domeny pod kątem zmian wygaśnięcia i dostępności. Otrzymuj alerty, gdy zarejestrowane domeny stają się dostępne.

Monitoruj domeny pod kątem zmian wygaśnięcia i dostępności. Otrzymuj alerty, gdy zarejestrowane domeny stają się dostępne.

Liczba domen, które możesz obserwować, zależy od Twojego planu. Konta bezpłatne mogą obserwować 5 domen. Konta płatne mogą obserwować jedną domenę na każde 30 kredytów miesięcznego planu, co wystarcza na codzienne sprawdzanie każdej domeny, co najmniej 100 i najwyżej 1000. Konta płatne bez planu miesięcznego mogą obserwować 100 domen. GET /v1/watchlist zwraca Twój bieżący limit jako max_domains. Dodanie ponad limit, duplikat lub nieprawidłowe dane są odrzucane i nie kosztują kredytów.

**Monitoring**

Zaloguj się przez Google, aby uzyskać dostęp do spersonalizowanej listy obserwowanych domen, alertów e-mail, webhooków i innych funkcji.

Otrzymuj powiadomienia przez e-mail, Telegram, Slack, Discord lub Webhook.

[Monitoring](https://domscan.net/pl/monitor)
[Ustawienia](https://domscan.net/pl/monitor/settings)
[Monitor marki](https://domscan.net/pl/brand-monitor-api)

GET /v1/watchlist

Pobierz wszystkie domeny na liście obserwacyjnej.

#### Przykładowa odpowiedź

```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"
                }
```

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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

Dodaj domenę do listy obserwacyjnej.

#### Treść żądania

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

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Zmień adres e-mail alertów domeny, która jest już na Twojej liście obserwowanych, bez usuwania jej i dodawania od nowa. Wyślij notify_email jako null, aby go wyczyścić; alerty dla tej domeny trafią wtedy na adres powiadomień Twojego konta. Aktualizacje są bezpłatne.

#### Treść żądania

```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"
```

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Usuń z listy obserwowanych

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

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Wkrótce wygasające

#### Przykładowa odpowiedź

```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
                }
```

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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

Dostępna

Z paginacją: wyślij `limit` (od 1 do 100) i przekaż `next_cursor` z powrotem jako `cursor`. Odpowiedzi zawierają `has_more` i `next_cursor`. Bez `limit` zwracana jest cała lista. Zobacz [paginację](https://domscan.net/docs/response-format#pagination).

#### Przykładowa odpowiedź

```json
{
                "available_domains": [
                {
                "domain": "startupdrop.ai",
                "status": "available",
                "last_checked": "2026-04-14T08:30:00Z",
                "check_count": 18
                }
                ],
                "total": 1,
                "message": "Te domeny z Twojej listy obserwowanych są teraz dostępne do rejestracji!"
                }
```

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

### Webhooki alertów

Otrzymuj alerty monitorowania jako podpisane żądania POST z JSON-em na własne endpointy HTTPS. Zarządzaj endpointami za pomocą klucza API lub, po zalogowaniu, w ustawieniach Monitora.

#### Typy zdarzeń

| Monitor | Zdarzenia |
| --- | --- |
| Dostępność, wygaśnięcie i status z listy obserwowanych | `domain.available`, `domain.expiring_30`, `domain.expiring_14`, `domain.expiring_7`, `domain.expiring_1`, `domain.status_change` |
| Monitorowanie zmian domen | `domain.dns_changed`, `domain.certificate_changed`, `domain.registration_changed`, `domain.hosting_changed`, `domain.technology_changed`, `domain.email_security_changed` |
| Monitorowanie marki (nowe rejestracje podobnych domen) | `brand.threat_detected` |
| Subskrypcje alertów listy obserwowanych (certyfikaty, ceny, rekordy DNS, domeny podobne) | `ssl.expiring`, `ssl.expired`, `ssl.changed`, `price.dropped`, `dns.changed`, `typosquat.detected` |
| Alerty o zmianach marki (logo, kolory, nazwa, profile społecznościowe) | `brand.updated` |
| Zadania asynchroniczne (bezpłatne, tylko dla zadań utworzonych z notify_webhook) | `job.completed`, `job.failed`, `job.cancelled` |
| Zdarzenie testowe (bezpłatne) | `webhook.test` |

[Przeczytaj przewodnik po API alertów webhook](https://domscan.net/pl/webhook-alerts-api)

#### Cennik

Każdy alert dostarczony do endpointu z odpowiedzią 2xx kosztuje 2 kredytów. Kredyty są rezerwowane tuż przed pierwszą próbą i zwracane, jeśli dostarczenie się nie powiedzie, zostanie anulowane lub endpoint zostanie usunięty. Zdarzenia testowe są bezpłatne. Gdy saldo jest zbyt niskie, alert jest pomijany i nic nie jest pobierane.

POST /v1/webhooks

Zarejestruj endpoint HTTPS. Adres URL musi wskazywać na publiczny adres. Pomiń events lub przekaż ["*"], aby otrzymywać każdy typ zdarzenia. Sekret podpisu jest zwracany tylko w tej odpowiedzi.

#### Przykładowe żądanie

```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"]
  }'
```

#### Przykładowa odpowiedź

```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_..."
}
```

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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

Wyświetla Twoje endpointy wraz ze statusem, subskrybowanymi zdarzeniami, liczbą błędów i czterema ostatnimi znakami sekretu, a także dostępne typy zdarzeń i zasady dostarczania.

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Wstrzymaj lub włącz endpoint, zmień jego zdarzenia albo edytuj opis. Włączenie endpointu zeruje licznik błędów.

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

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Usuwa endpoint. Oczekujące dostarczenia są anulowane, a zarezerwowane kredyty zwracane.

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `id` | string |
| `deleted` | boolean |

#### Przykładowa odpowiedź

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

POST /v1/webhooks/:webhook_id/test

Wysyła jedno bezpłatne zdarzenie webhook.test i zwraca wynik. Zdarzenia testowe nie są ponawiane i nie wliczają się do automatycznego wstrzymania.

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Zastępuje sekret podpisu endpointu, także wstrzymanego. Nowy sekret jest zwracany tylko w tej odpowiedzi. Przez kolejne 24 godziny każde dostarczenie jest podpisywane zarówno nowym, jak i poprzednim sekretem. Rotacja jest bezpłatna.

#### Przykładowe żądanie

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

#### Przykładowa odpowiedź

```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
}
```

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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

#### Parametry zapytania

| Parametr | Typ | Opis |
| --- | --- | --- |
| limit | integer | Liczba dostarczeń do zwrócenia, od 1 do 100. Domyślnie 50. |

Wyświetla ostatnie dostarczenia ze statusem, próbami, odpowiedzią HTTP, pobranymi kredytami i zwrotami. Rekordy dostarczeń są przechowywane przez 30 dni.

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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"
    }
  ]
}
```

#### Format żądania

Każdy alert to żądanie POST z treścią JSON. Pole id pozostaje takie samo dla danego zdarzenia i jest powtórzone w X-DomScan-Event-Id, dzięki czemu możesz ignorować ponowienia, które już przetworzono.

```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"
  }
}
```

#### Weryfikacja podpisów

Oblicz HMAC-SHA256 z wartości X-DomScan-Timestamp, kropki i surowej treści żądania, używając sekretu swojego endpointu. Porównaj wynik z X-DomScan-Signature w stałym czasie i odrzucaj żądania ze znacznikiem czasu starszym niż 5 min.

Poniższy przykład sprawdza każdy podpis w nagłówku, więc działa także podczas rotacji sekretu.

```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);
  });
}
```

#### Zmiana sekretu podpisu

W 24-godzinnym okresie przejściowym po rotacji nagłówek X-DomScan-Signature zawiera dwa podpisy oddzielone przecinkiem, z nowym sekretem na pierwszym miejscu, jak pokazano poniżej. Przyjmij żądanie, gdy którykolwiek wpis pasuje do sekretu, któremu ufasz, wdróż nowy sekret, a potem przestań ufać staremu. Ponowna rotacja w okresie przejściowym natychmiast unieważnia starszy poprzedni sekret.

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

#### Ponowienia i automatyczne wstrzymanie

Zwróć dowolny status 2xx w ciągu 8 sekund, aby potwierdzić alert. Przekierowania, inne kody statusu i przekroczenia czasu są ponawiane z wykładniczym opóźnieniem (1, 4, 16, 64 i 256 minut), łącznie do 6 prób. Po 15 kolejnych nieudanych próbach endpoint zostaje wstrzymany; włącz go ponownie przez PATCH lub w ustawieniach Monitora.

Gdy endpoint zostanie wstrzymany po powtarzających się błędach, jego właściciel otrzymuje jeden e-mail z hostem endpointu, ostatnim błędem i linkiem do ustawień Monitoringu. Napraw endpoint, a następnie włącz go ponownie w ustawieniach Monitoringu lub przez PATCH z enabled ustawionym na true. Włączenie zeruje licznik błędów.

### Subskrypcje alertów listy obserwowanych

Zasubskrybuj dla obserwowanego elementu alerty, które chcesz otrzymywać. Każda subskrypcja obserwuje jedną nazwę hosta, TLD lub domenę marki, a Ty wybierasz, które z jej zdarzeń otrzymujesz. Zdarzenia trafiają do Twoich podpisanych punktów końcowych webhook oraz do alertów w aplikacji.

| Typ | Zdarzenia | Kiedy się uruchamia |
| --- | --- | --- |
| `ssl` | `ssl.expiring`, `ssl.expired`, `ssl.changed` | ssl.expiring, gdy certyfikat używany przez nazwę hosta wygasa w ciągu ssl_expiring_days (30, 14, 7 lub 1, domyślnie 14), raz na certyfikat i próg. ssl.expired raz na każdy wygasły certyfikat. ssl.changed, gdy nowy odcisk certyfikatu zostanie zauważony w dwóch kolejnych kontrolach; ładunek informuje, czy zmienił się wystawca. |
| `price` | `price.dropped` | Gdy cena rejestracji lub odnowienia TLD, u jednego rejestratora lub u najtańszego, spadnie o co najmniej drop_percent względem najwyższej ceny od ostatniego alertu albo osiągnie target_price lub mniej. Ceny pochodzą z dziennej migawki cen, a każda migawka jest oceniana raz. |
| `dns` | `dns.changed` | Gdy obserwowany typ rekordu (A, AAAA, MX, NS, TXT lub CNAME) dowolnej nazwy hosta zwraca tę samą nową odpowiedź w dwóch kolejnych potwierdzonych zapytaniach. |
| `typosquat` | `typosquat.detected` | Gdy nowo zarejestrowano domenę podobną do domeny marki, co potwierdza autorytatywne sprawdzenie rejestracji. Pierwszy pełny przebieg po domenach podobnych ustala stan bazowy i nie wysyła alertu. |
| `brand` | `brand.updated` | Gdy kwadratowe logo, szerokie logo, kolory, nazwa lub zadeklarowane profile społecznościowe domeny marki ulegną zmianie, a zmiana zostanie zobaczona ponownie przy następnej kontroli. Wybierz, które z nich, za pomocą attributes (logo, wide_logo, colors, name, socials; domyślnie wszystkie). Pierwsza kontrola ustala stan wyjściowy i nie wysyła alertu, a atrybut, którego nie udało się sprawdzić, pozostaje bez zmian. |

Zdarzenie wyzwalają tylko dokładne dowody. Nieudany handshake TLS, zapytanie DNS, które się nie powiodło lub przekroczyło limit czasu, brak ceny oraz zapytanie zablokowane lub ograniczone limitem mają status nieznany: nic nie zmieniają i nigdy nie powodują alertu ani opłaty. Pierwsza potwierdzona kontrola subskrypcji ustala jej stan bazowy.

Kontrole działają automatycznie: certyfikaty co 12 godzin, rekordy DNS co godzinę (z kontrolą potwierdzającą 15 minut po pierwszym zauważeniu zmiany), ceny co 2 godziny względem dziennej migawki, a domeny podobne w partiach po 30 z pełnym przebiegiem każdego dnia. Po kontroli o nieznanym wyniku kolejna próba następuje wcześniej. Subskrypcje marek są sprawdzane raz dziennie, z kontrolą potwierdzającą 90 minut po pierwszym wykryciu zmiany.

Tworzenie subskrypcji i wykonywanie kontroli jest bezpłatne. Każdy alert dostarczony do punktu końcowego webhook z odpowiedzią 2xx kosztuje 2 kredytów, tak jak każdy inny alert monitorowania. Nieudane dostarczenia są zwracane, a konto może mieć do 100 subskrypcji, w tym 20 dla domen podobnych.

POST /v1/watchlist/alerts

Utwórz subskrypcję. type decyduje o tym, które pola obowiązują: domain dla ssl, dns i typosquat; tld, registrar, price_type, drop_percent i target_price dla price. Pola, które nie dotyczą danego typu, są odrzucane.

#### Treść żądania

| Parametr | Typ | Opis |
| --- | --- | --- |
| type | string | ssl, price, dns lub typosquat. Wymagane. |
| domain | string | Nazwa hosta do obserwowania dla ssl i dns albo domena marki dla typosquat. |
| tld | string | TLD do obserwowania dla price, na przykład com. |
| registrar | string | Identyfikator rejestratora dla price. Pomiń, aby obserwować najtańszego rejestratora. |
| events | string[] | Zdarzenia do otrzymywania. Domyślnie wszystkie zdarzenia danego typu. |
| ssl_expiring_days | integer | Liczba dni przed wygaśnięciem dla ssl.expiring: 30, 14, 7 lub 1. Domyślnie 14. |
| price_type | string | registration (domyślnie) lub renewal. |
| drop_percent | number | Powiadom o spadku o co najmniej tyle procent, od 1 do 95. |
| target_price | number | Powiadom, gdy cena w USD osiągnie tę kwotę lub mniej. Subskrypcja cenowa wymaga drop_percent, target_price lub obu. |
| record_types | string[] | Typy rekordów do obserwowania dla dns. Domyślnie A, AAAA, MX, NS, TXT i CNAME. |
| notify_email | string | Opcjonalne. Wysyła też każdy alert tej subskrypcji e-mailem na ten adres (3 kredyty za każdy wysłany e-mail). Dostarczanie przez webhook się nie zmienia. Zmień go później przez PATCH albo wyślij null, aby zatrzymać e-maile. |

#### Przykładowe żądanie

```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
  }'
```

#### Przykładowa odpowiedź

```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"
  }
}
```

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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

Wyświetl swoje subskrypcje wraz z ostatnimi potwierdzonymi dowodami i stanem kontroli, zdarzeniami obsługiwanymi przez każdy typ, harmonogramem kontroli i ceną alertu.

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Pobierz jedną subskrypcję wraz z ostatnimi potwierdzonymi dowodami i 20 najnowszymi zdarzeniami.

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Wstrzymaj lub wznów subskrypcję za pomocą enabled albo zmień events, ssl_expiring_days, drop_percent, target_price lub record_types. Nowa cena docelowa wywoła alert dopiero przy późniejszej zmianie ceny.

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

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

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `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 |

#### Przykładowa odpowiedź

```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

Usuń subskrypcję. Zdarzenia, które jeszcze nie zostały wysłane, są odrzucane i nigdy nie są rozliczane.

#### Pola odpowiedzi

| Pole | Typ |
| --- | --- |
| `id` | string |
| `deleted` | boolean |

#### Przykładowa odpowiedź

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

#### Przykładowe zdarzenie 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"
  }
}
```
