Referência para desenvolvedores

Lista de Observação de Domínio

API da DomScan: Monitore domínios para mudanças de expiração e disponibilidade. Receba alertas quando domínios registrados ficarem disponíveis.

Lista de Observação de Domínio

Monitore domínios para mudanças de expiração e disponibilidade. Receba alertas quando domínios registrados ficarem disponíveis.

Monitorar

Entre com o Google para acessar sua lista de observação de domínio personalizada com alertas de email, webhooks e muito mais.

Receba notificações por e-mail, Telegram, Slack, Discord ou Webhook.

Monitorar Configurações Monitor de marca

GET /v1/watchlist

Obtenha todos os domínios em sua lista de observação.

Paginado: envie limit (de 1 a 100) e passe next_cursor de volta como cursor. As respostas incluem has_more e next_cursor. Sem limit, a lista completa é retornada. Veja a paginação.

Exemplo de resposta

{
                "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,
                "updated_at": "2024-03-01T12:00:00Z"
                }

Campos da resposta

Campo	Tipo
`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
`updated_at`	string

POST /v1/watchlist

Adicione um domínio à sua lista de observação.

Corpo da requisição

{
                "domain": "mydomain.com",
                "notify_email": "[email protected]"
                }

Campos da resposta

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

Exemplo de resposta

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

DELETE /v1/watchlist?domain=mydomain.com

Remover da lista de observação

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

Campos da resposta

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

Exemplo de resposta

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

GET /v1/watchlist/expiring?days=30

Expirando em breve

Paginado: envie limit (de 1 a 100) e passe next_cursor de volta como cursor. As respostas incluem has_more e next_cursor. Sem limit, a lista completa é retornada. Veja a paginação.

Exemplo de resposta

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

Campos da resposta

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

Disponível

Paginado: envie limit (de 1 a 100) e passe next_cursor de volta como cursor. As respostas incluem has_more e next_cursor. Sem limit, a lista completa é retornada. Veja a paginação.

Exemplo de resposta

{
                "available_domains": [
                {
                "domain": "startupdrop.ai",
                "status": "available",
                "last_checked": "2026-04-14T08:30:00Z",
                "check_count": 18
                }
                ],
                "total": 1,
                "message": "Estes domínios da sua lista de observação agora estão disponíveis para registro!"
                }

Campos da resposta

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

Webhooks de alertas

Receba alertas de monitoramento como requisições POST JSON assinadas nos seus próprios endpoints HTTPS. Gerencie os endpoints com uma chave de API ou, depois de entrar na conta, pelas configurações do Monitor.

Tipos de evento

Monitor	Eventos
Disponibilidade, expiração e status da lista de observação	`domain.available` `domain.expiring_30` `domain.expiring_14` `domain.expiring_7` `domain.expiring_1` `domain.status_change`
Monitoramento de mudanças de domínio	`domain.dns_changed` `domain.certificate_changed` `domain.registration_changed` `domain.hosting_changed` `domain.technology_changed` `domain.email_security_changed`
Monitoramento de marca (novos registros semelhantes)	`brand.threat_detected`
Assinaturas de alerta da lista de observação (certificados, preços, registros DNS, domínios parecidos)	`ssl.expiring` `ssl.expired` `ssl.changed` `price.dropped` `dns.changed` `typosquat.detected`
Jobs assíncronos (gratuito, apenas para jobs criados com notify_webhook)	`job.completed` `job.failed` `job.cancelled`
Evento de teste (gratuito)	`webhook.test`

Leia o guia da API de alertas webhook

Preços

Cada alerta entregue a um endpoint com uma resposta 2xx custa 2 créditos. Os créditos são reservados imediatamente antes da primeira tentativa e reembolsados se a entrega falhar, for cancelada ou se o endpoint for excluído. Os eventos de teste são gratuitos. Quando o saldo é insuficiente, o alerta é ignorado e nada é cobrado.

POST /v1/webhooks

Cadastra um endpoint HTTPS. A URL deve resolver para um endereço público. Omita events, ou envie ["*"], para receber todos os tipos de evento. O segredo de assinatura é retornado somente nesta resposta.

Exemplo de requisição

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

Exemplo de resposta

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

Campos da resposta

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

Lista seus endpoints com status, eventos assinados, contagem de falhas e os quatro últimos caracteres do segredo, junto com os tipos de evento disponíveis e a política de entrega.

Campos da resposta

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

Exemplo de resposta

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

Pausa ou ativa um endpoint, altera seus eventos ou edita sua descrição. Ativar um endpoint zera a contagem de falhas.

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

Campos da resposta

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

Exemplo de resposta

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

Exclui um endpoint. As entregas pendentes são canceladas e os créditos reservados são reembolsados.

Campos da resposta

Campo	Tipo
`id`	string
`deleted`	boolean

Exemplo de resposta

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

POST /v1/webhooks/:webhook_id/test

Envia um evento webhook.test gratuito e retorna o resultado. Os eventos de teste não são repetidos e não contam para a pausa automática.

Campos da resposta

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

Exemplo de resposta

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

Substitui o segredo de assinatura de um endpoint, inclusive de um endpoint pausado. O novo segredo é retornado somente nesta resposta. Nas próximas 24 horas, cada entrega é assinada com o segredo novo e com o anterior. A rotação é gratuita.

Exemplo de requisição

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

Exemplo de resposta

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

Campos da resposta

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

Parâmetros de consulta

Parâmetro	Tipo	Descrição
limit	integer	Número de entregas a retornar, de 1 a 100. Padrão: 50.

Lista as entregas recentes com status, tentativas, resposta HTTP, créditos cobrados e reembolsos. Os registros de entrega são mantidos por 30 dias.

Campos da resposta

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

Exemplo de resposta

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

Formato da requisição

Cada alerta é uma requisição POST com corpo JSON. O campo id permanece o mesmo para um evento e se repete em X-DomScan-Event-Id, então você pode ignorar novas tentativas que já processou.

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

Verificar assinaturas

Calcule um HMAC-SHA256 do valor de X-DomScan-Timestamp, de um ponto e do corpo bruto da requisição, usando o segredo do seu endpoint. Compare o resultado com X-DomScan-Signature em tempo constante e rejeite requisições cujo timestamp tenha mais de 5 minutos.

O exemplo abaixo verifica todas as assinaturas do cabeçalho, então continua funcionando durante uma rotação de segredo.

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

Rotacionar um segredo de assinatura

Durante o período de carência de 24 horas após uma rotação, X-DomScan-Signature contém duas assinaturas separadas por vírgula, com o segredo novo primeiro, como mostrado abaixo. Aceite uma requisição quando qualquer entrada corresponder a um segredo em que você confia, implante o novo segredo e depois deixe de confiar no antigo. Rotacionar novamente durante o período de carência encerra imediatamente o segredo anterior mais antigo.

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

Novas tentativas e pausa automática

Retorne qualquer status 2xx em até 8 segundos para confirmar um alerta. Redirecionamentos, outros códigos de status e timeouts são repetidos com backoff exponencial (1, 4, 16, 64 e 256 minutos), até 6 tentativas no total. Após 15 tentativas consecutivas com falha, o endpoint é pausado; ative-o novamente com PATCH ou pelas configurações do Monitor.

Quando um endpoint é pausado após falhas repetidas, o proprietário do endpoint recebe um e-mail com o host do endpoint, o último erro e um link para as configurações do Monitor. Corrija o endpoint e ative-o novamente nas configurações do Monitor ou com PATCH e enabled definido como true. Ao ativá-lo, a contagem de falhas volta a zero.

Assinaturas de alerta da lista de observação

Assine os alertas que quiser para um item observado. Cada assinatura observa um hostname, um TLD ou um domínio de marca, e você escolhe quais eventos receber. Os eventos vão para seus endpoints de webhook assinados e para seus alertas no app.

Tipo	Eventos	Quando dispara
`ssl`	`ssl.expiring` `ssl.expired` `ssl.changed`	ssl.expiring quando o certificado servido por um hostname expira dentro de ssl_expiring_days (30, 14, 7 ou 1, padrão 14), uma vez por certificado e limite. ssl.expired uma vez por certificado expirado. ssl.changed quando uma nova impressão digital de certificado é vista em duas verificações consecutivas; o payload informa se o emissor mudou.
`price`	`price.dropped`	Quando o preço de registro ou de renovação de um TLD, em um registrador ou no mais barato, cai pelo menos drop_percent em relação ao preço mais alto desde o último alerta, ou chega a target_price ou menos. Os preços vêm do snapshot diário de preços, e cada snapshot é avaliado uma única vez.
`dns`	`dns.changed`	Quando um tipo de registro observado (A, AAAA, MX, NS, TXT ou CNAME) de qualquer hostname retorna a mesma resposta nova em duas consultas confirmadas consecutivas.
`typosquat`	`typosquat.detected`	Quando um domínio parecido com o domínio de marca é registrado pela primeira vez, confirmado por uma consulta de registro autoritativa. A primeira passagem completa pelos domínios parecidos define a linha de base e não gera alerta.

Somente evidências exatas disparam um evento. Um handshake TLS que falha, uma consulta DNS que falha ou expira, um preço ausente e uma consulta bloqueada ou com limite de taxa são desconhecidos: não mudam nada e nunca geram alerta nem cobrança. A primeira verificação confirmada de uma assinatura define sua linha de base.

As verificações rodam automaticamente: certificados a cada 12 horas, registros DNS a cada hora (com uma verificação de confirmação 15 minutos depois de a mudança ser vista pela primeira vez), preços a cada 2 horas em relação ao snapshot diário, e domínios parecidos em lotes de 30 com uma passagem completa por dia. Depois de uma verificação desconhecida, a próxima tentativa acontece mais cedo.

Criar assinaturas e executar verificações é grátis. Cada alerta entregue a um endpoint de webhook com resposta 2xx custa 2 créditos, como qualquer outro alerta de monitoramento. As entregas com falha são reembolsadas, e uma conta pode ter até 100 assinaturas, 20 delas para domínios parecidos.

POST /v1/watchlist/alerts

Cria uma assinatura. type define quais campos se aplicam: domain para ssl, dns e typosquat; tld, registrar, price_type, drop_percent e target_price para price. Campos que não se aplicam ao tipo são rejeitados.

Corpo da requisição

Parâmetro	Tipo	Descrição
type	string	ssl, price, dns ou typosquat. Obrigatório.
domain	string	Hostname a observar para ssl e dns, ou o domínio de marca para typosquat.
tld	string	TLD a observar para price, por exemplo com.
registrar	string	ID do registrador para price. Omita para observar o registrador mais barato.
events	string[]	Eventos a receber. Por padrão, todos os eventos do tipo.
ssl_expiring_days	integer	Dias antes da expiração para ssl.expiring: 30, 14, 7 ou 1. Padrão 14.
price_type	string	registration (padrão) ou renewal.
drop_percent	number	Alerta em uma queda de pelo menos esta porcentagem, de 1 a 95.
target_price	number	Alerta quando o preço em USD chega a este valor ou menos. Uma assinatura de preço precisa de drop_percent, target_price ou ambos.
record_types	string[]	Tipos de registro a observar para dns. Por padrão A, AAAA, MX, NS, TXT e CNAME.

Exemplo de requisição

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

Exemplo de resposta

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

Campos da resposta

Campo	Tipo
`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.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

Lista suas assinaturas com a evidência confirmada mais recente e o status das verificações, os eventos aceitos por cada tipo, o cronograma de verificações e o preço do alerta.

Campos da resposta

Campo	Tipo
`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[].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[]
`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.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

Exemplo de resposta

{
  "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"
      ],
      "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"
    ]
  },
  "policy": {
    "credits_per_delivered_alert": 2,
    "check_credits": 0,
    "unknown_checks_charged": false,
    "max_subscriptions": 1,
    "check_interval_minutes": {},
    "max_typosquat_subscriptions": 1,
    "ssl_expiring_days": [
      1
    ],
    "default_ssl_expiring_days": 1,
    "record_types": [
      "A"
    ],
    "price_types": [
      "registration"
    ],
    "confirmation_checks": {}
  }
}

GET /v1/watchlist/alerts/:subscription_id

Obtém uma assinatura com a evidência confirmada mais recente e seus 20 eventos mais recentes.

Campos da resposta

Campo	Tipo
`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.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

Exemplo de resposta

{
  "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"
    ],
    "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

Pausa ou retoma uma assinatura com enabled, ou altera seus events, ssl_expiring_days, drop_percent, target_price ou record_types. Um novo preço-alvo só gera alerta em uma variação de preço posterior.

{ "enabled": false }

Campos da resposta

Campo	Tipo
`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.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

Exemplo de resposta

{
  "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"
    ],
    "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

Exclui uma assinatura. Os eventos que ela ainda não enviou são descartados e nunca cobrados.

Campos da resposta

Campo	Tipo
`id`	string
`deleted`	boolean

Exemplo de resposta

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

Exemplo de evento 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"
  }
}