API REFERENCE

Webhooks

Receive a POST request to your server when a scan completes. Each delivery is signed with HMAC-SHA256 so you can verify it came from webdoc.ai.

Events

Payload

{
  "event": "scan.completed",
  "scan_id": "c4f1a2b3-...",
  "url": "https://example.com",
  "score": 54,
  "data": {
    "domain": "example.com",
    "verdict": "Needs Work"
  }
}

Request headers

Verifying signatures

import { createHmac } from "crypto"

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex")
  return expected === signature
}

// In your route handler:
const body = await request.text()
const sig = request.headers.get("x-webdoc-signature") ?? ""
if (!verifyWebhook(body, sig, process.env.WEBHOOK_SECRET!)) {
  return new Response("Unauthorized", { status: 401 })
}
const payload = JSON.parse(body)

Managing webhook endpoints

The webhook secret is returned once when you register the endpoint. Store it securely — it cannot be retrieved later. Delete and re-register to rotate a lost secret.