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.
Lista obserwacyjna domen
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.
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.
Pobierz wszystkie domeny na liście obserwacyjnej.
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ę.
Przykładowa odpowiedź
{
"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": "[email protected]",
"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 |
Dodaj domenę do listy obserwacyjnej.
Treść żądania
{
"domain": "mydomain.com",
"notify_email": "[email protected]"
}
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ź
{
"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": "[email protected]"
},
{
"domain": "example.org",
"added_at": "2026-10-09T10:15:30.000Z",
"status": "unknown",
"notify_email": "[email protected]"
}
],
"total": 2,
"max_domains": 333,
"limit_basis": "monthly_credits"
}
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
{
"notify_email": "[email protected]"
}
curl -X PATCH -H "X-API-Key: your-api-key" -H "Content-Type: application/json" -d '{"notify_email":"[email protected]"}' "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ź
{
"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": "[email protected]",
"check_count": 12
}
}
Usuń z listy obserwowanych
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ź
{
"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": "[email protected]",
"check_count": 1
}
],
"total": 1
}
Wkrótce wygasające
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ę.
Przykładowa odpowiedź
{
"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 |
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ę.
Przykładowa odpowiedź
{
"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
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.
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
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ź
{
"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 |
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ź
{
"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"
}
Wstrzymaj lub włącz endpoint, zmień jego zdarzenia albo edytuj opis. Włączenie endpointu zeruje licznik błędów.
{ "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ź
{
"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"
}
}
Usuwa endpoint. Oczekujące dostarczenia są anulowane, a zarezerwowane kredyty zwracane.
Pola odpowiedzi
| Pole | Typ |
|---|---|
id |
string |
deleted |
boolean |
Przykładowa odpowiedź
{
"id": "example-id",
"deleted": true
}
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ź
{
"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
}
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
curl -X POST "https://domscan.net/v1/webhooks/whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3/rotate-secret" \
-H "X-API-Key: $DOMSCAN_API_KEY"
Przykładowa odpowiedź
{
"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 |
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ź
{
"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.
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.
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.
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.
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
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ź
{
"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 |
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ź
{
"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": "[email protected]",
"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": {}
}
}
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ź
{
"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": "[email protected]",
"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": {}
}
]
}
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.
{ "enabled": false }
{ "notify_email": "[email protected]" }
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ź
{
"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": "[email protected]",
"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"
}
}
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ź
{
"id": "example-id",
"deleted": true
}
Przykładowe zdarzenie dns.changed
{
"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"
}
}