API documentation
Register merchant URLs, start scans and receive signed verdicts by webhook.
How a scan reaches you
Everything is asynchronous. You register a URL once, start scans when you need one, and WatchURL pushes the verdict to your webhook. A periodic reconciliation call catches anything your endpoint missed.
Scroll sideways to see the whole flow.
Never block on a scan
Starting a scan returns 202 at once. Scans take 22s at the median and about 130s at p95.
Webhooks first
Push delivery is faster and uses none of your rate limit. Poll only if you cannot expose an endpoint.
Reconcile on a timer
List checks finished since your last sweep every 10-15 minutes so a missed webhook is never a missed verdict.
Create an API key and a webhook
Create a key under API keys and a webhook endpoint under Webhooks. Copy the webhook signing secret: you need it to verify every delivery. Keep both on your server only.
// .env on your server
WATCHURL_API_KEY=kyw_live_...
WATCHURL_WEBHOOK_SECRET=... // from the Webhooks page
const WATCHURL = 'https://watchurl.ai/api/v1'
const headers = {
'Authorization': 'Bearer ' + process.env.WATCHURL_API_KEY,
'Content-Type': 'application/json',
}Register the URL profile
Register each merchant URL once and store the returned id next to your merchant record. Pass your own id as external_id so webhooks can be matched back without a lookup table.
const res = await fetch(WATCHURL + '/url-profiles', {
method: 'POST',
headers,
body: JSON.stringify({
name: 'Acme Store',
url: 'https://acme.com',
declared_category: 'Retail & Shopping',
check_frequency_hours: 24, // or 'daily', 'weekly', 'monthly'
max_pages: 3,
external_id: merchant.id, // your id, echoed back in webhooks
}),
})
if (res.status === 402) throw new Error('URL profile limit reached for this plan')
if (!res.ok) throw new Error('Register failed: ' + res.status)
const { data: profile } = await res.json()
await db.merchants.update(merchant.id, { watchurl_profile_id: profile.id })Response 201 Created
{
"data": {
"id": "8a2e…",
"name": "Acme Store",
"url": "https://acme.com",
"external_id": "your-merchant-123",
"declared_category": "Retail & Shopping",
"status": "active",
"check_frequency_hours": 24,
"max_pages_per_check": 3,
"created_at": "2026-10-09T08:52:58Z"
}
}Start a scan
Starting a scan returns 202 straight away. Mark the merchant as pending in your system and return to your user; do not hold a request open waiting for the verdict.
const res = await fetch(WATCHURL + '/checks', {
method: 'POST',
headers,
body: JSON.stringify({ url_profile_id: profile.id }),
})
if (res.status === 409) {
// Already scanning this profile: track that scan instead of starting another
const { running_check_id } = await res.json()
return running_check_id
}
if (res.status === 429) {
const wait = Number(res.headers.get('Retry-After') || 60)
return queueForLater(profile.id, wait) // see "Errors and retries"
}
if (!res.ok) throw new Error('Start scan failed: ' + res.status)
const { check_run_id } = await res.json()
await db.merchants.update(merchant.id, { status: 'pending_verification', watchurl_check_id: check_run_id })Response 202 Accepted
{
"success": true,
"check_run_id": "c1f0…",
"status": "queued",
"pages_to_scan": 3,
"message": "Check queued — results will appear within 30-60 seconds"
}Receive the verdict by webhook
When the scan finishes WatchURL POSTs check.completed to your endpoint. Verify the signature, record the event id, reply 200, then act on the verdict in the background.
import crypto from 'crypto'
export async function POST(req) {
const raw = await req.text() // verify the raw body, not re-serialised JSON
const given = req.headers.get('x-watchurl-signature') || ''
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.WATCHURL_WEBHOOK_SECRET)
.update(raw)
.digest('hex')
const ok = given.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
if (!ok) return new Response('Invalid signature', { status: 401 })
const event = JSON.parse(raw)
// Retries reuse the same event_id: process each one once
const firstTime = await db.webhookEvents.insertIfAbsent(event.event_id)
if (!firstTime) return new Response('Duplicate', { status: 200 })
await jobs.enqueue('handle-watchurl-event', event) // do the work after replying
return new Response('OK', { status: 200 })
}
// Background job
async function handleWatchurlEvent(event) {
const { verdict, merchant, site_status } = event.data
// The site itself could not be read: act on why, not on the verdict
if (site_status.status === 'offline') return markMerchantOffline(merchant.external_id, site_status.message)
if (site_status.status === 'blocked' || site_status.status === 'login_required') return queueManualReview(merchant.external_id, event.data)
switch (verdict.result) {
case 'PASS': return activateMerchant(merchant.external_id)
case 'REVIEW': return queueManualReview(merchant.external_id, event.data)
case 'FAIL': return holdMerchant(merchant.external_id, verdict.reason)
}
}Reconcile anything you missed
Webhooks can still be lost if your endpoint is down through every retry. Every 10 to 15 minutes, list checks that finished since your last sweep and process any you have not seen. The event-id check above keeps this safe to repeat.
async function reconcile() {
const since = await db.settings.get('watchurl_last_sweep') // ISO time
const startedAt = new Date().toISOString()
const res = await fetch(WATCHURL + '/checks?limit=100&since=' + encodeURIComponent(since), { headers })
const { data: checks } = await res.json()
for (const check of checks) {
if (await db.checksSeen.has(check.id)) continue
if (check.status === 'completed') {
const full = await fetch(WATCHURL + '/checks/' + check.id, { headers }).then(r => r.json())
await handleCheckResult(full.data)
} else if (check.status === 'failed' || check.status === 'blocked') {
await markScanFailed(check.merchant_id, check.failure_reason) // not billed; retry later
}
}
await db.settings.set('watchurl_last_sweep', startedAt)
}