Skip to content

Webhooks

ScanFree can send a signed POST to your own address when something happens on your account, so Zapier, n8n or your agent can act on it instead of asking again and again.

Add an endpoint on your MCP & API page: an https address and the events it should get. You can have several. The signing secret is shown once, when you add it: keep it with the code that receives the webhooks.

Events

EventWhen
scan.finishedA free scan of yours finished (or could not run).
check.finishedA check of a paid order finished: named counts, the same figures as the check email, and the facts check's counts.
order.paidAn order was paid: its first payment, or a monthly payment.
order.stoppedAn order was stopped: by you, by us, or because a payment went unpaid.
program.unlockedThe programs (directory, press release, blog distribution) became available on an order.

Counts come with their totals (“named in 17 of 60 live answers”), never as a bare percentage, and live search and training data are kept apart. A payload carries ids, counts and links only: never answer text. Follow the link, or ask our MCP server, for the details.

The payload

Every delivery is JSON with the same four fields: id (the event’s id, the same on every retry: use it to handle each event once), type, created_at and data.

scan.finished

Example shape; values are illustrative
{
  "id": "evt_8c1f0d6a2b5e4f7a9c3d1e2f4a6b8c0d",
  "type": "scan.finished",
  "created_at": "2026-11-21T09:14:05.000Z",
  "data": {
    "scan_id": "3f1c2a9e-0000-4000-8000-000000000000",
    "site_id": "5a7e9c10-0000-4000-8000-000000000000",
    "status": "complete",
    "answers": {
      "answered": 28,
      "asked": 30
    },
    "links": {
      "results": "https://app.scanfree.dev/app/scans/3f1c2a9e-0000-4000-8000-000000000000"
    }
  }
}

check.finished

Example shape; values are illustrative
{
  "id": "evt_8c1f0d6a2b5e4f7a9c3d1e2f4a6b8c0d",
  "type": "check.finished",
  "created_at": "2026-11-21T09:14:05.000Z",
  "data": {
    "check_id": "3f1c2a9e-0000-4000-8000-000000000000",
    "order_id": "8b2d6e41-0000-4000-8000-000000000000",
    "kind": "scheduled",
    "seq": 3,
    "status": "complete",
    "finished_at": "2026-11-21T09:14:03.000Z",
    "named": {
      "live_search": {
        "named": 17,
        "total": 60
      },
      "training_data": {
        "named": 4,
        "total": 20
      }
    },
    "runs": {
      "answered": 80,
      "named": 21,
      "not_run": 0
    },
    "facts": {
      "answers_read": 21,
      "not_checked": 0,
      "new_flags": 1,
      "open_flags": 2,
      "topics": {
        "phone": 1,
        "hours": 1
      },
      "listings": 0
    },
    "links": {
      "results": "https://app.scanfree.dev/app/orders/8b2d6e41-0000-4000-8000-000000000000?check=3f1c2a9e-0000-4000-8000-000000000000#check"
    }
  }
}

order.paid

Example shape; values are illustrative
{
  "id": "evt_8c1f0d6a2b5e4f7a9c3d1e2f4a6b8c0d",
  "type": "order.paid",
  "created_at": "2026-11-21T09:14:05.000Z",
  "data": {
    "order_id": "8b2d6e41-0000-4000-8000-000000000000",
    "payment": "monthly",
    "amount_cents": 4900,
    "currency": "usd",
    "links": {
      "order": "https://app.scanfree.dev/app/orders/8b2d6e41-0000-4000-8000-000000000000"
    }
  }
}

order.stopped

Example shape; values are illustrative
{
  "id": "evt_8c1f0d6a2b5e4f7a9c3d1e2f4a6b8c0d",
  "type": "order.stopped",
  "created_at": "2026-11-21T09:14:05.000Z",
  "data": {
    "order_id": "8b2d6e41-0000-4000-8000-000000000000",
    "state": "cancelled",
    "stopped_by": "customer",
    "links": {
      "order": "https://app.scanfree.dev/app/orders/8b2d6e41-0000-4000-8000-000000000000"
    }
  }
}

program.unlocked

Example shape; values are illustrative
{
  "id": "evt_8c1f0d6a2b5e4f7a9c3d1e2f4a6b8c0d",
  "type": "program.unlocked",
  "created_at": "2026-11-21T09:14:05.000Z",
  "data": {
    "order_id": "8b2d6e41-0000-4000-8000-000000000000",
    "programs": [
      "directory",
      "press",
      "blog"
    ],
    "links": {
      "programs": "https://app.scanfree.dev/app/orders/8b2d6e41-0000-4000-8000-000000000000#programs"
    }
  }
}

check.finished also carries facts, the facts check’s counts for that check (included in every paid order): answers read, answers not checked, new and open flags, flags per topic, and listing flags. Counts and topics only, never a quote or a phone number; it is null when the facts check didn’t run. Listing differences can arrive a few minutes after the check, so the order page may show more.

scan.finished is sent for your own scans; the scans of a paid check send check.finished instead. Send test delivers a webhook.test event once.

Check the signature

Each request has the header ScanFree-Signature: t=<unix seconds>,v1=<signature>. The signature is the hex HMAC-SHA256 of the timestamp, a dot and the raw body (t + "." + body), with your signing secret as the key. Refuse a request whose timestamp is more than 5 minutes from your clock: that stops someone replaying an old one. The headers ScanFree-Event and ScanFree-Delivery name the event type and the delivery.

verify.js
// Node.js 18+: check a ScanFree webhook before you trust it
import crypto from "node:crypto";

export function verifyScanFree(rawBody, header, secret, toleranceSeconds = 300) {
  // header: "t=1763716445,v1=5f2b…" (read the raw body, before any JSON parsing)
  const parts = Object.fromEntries(String(header || "").split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;   // too old or from the future: a replay
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex"), b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post("/scanfree-webhook", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyScanFree(req.body.toString("utf8"), req.get("ScanFree-Signature"), process.env.SCANFREE_WEBHOOK_SECRET)) return res.sendStatus(400);
//   const event = JSON.parse(req.body); /* handle event.type, once per event.id */ res.sendStatus(200);
// });

Answers, retries and turning off

  • Answer with any 2xx status within 10 seconds. Do the work afterwards.
  • Anything else is a failure: another status, a timeout, a refused connection, or a redirect (we never follow one: give the final address).
  • A failed delivery is tried again with doubling waits, at most 6 hours apart, for 24 hours: about 1 min, 3 min, 7 min, 15 min, 31 min after the event, and so on (12 tries in all). The same event can arrive more than once: use its id.
  • An endpoint that has failed for 3 days with no success in between is turned off, and we email you. Turn it on again on the same page once it’s fixed; events from while it was off aren’t sent again.
  • The delivery log on the page keeps 30 days: the status, your answer’s code and how long it took, with at most 500 characters of your answer.

Safety

  • https addresses only.
  • The address must be on the public internet: like our crawler, we refuse private, loopback and cloud-metadata addresses, when you add it and again on every delivery.
  • We read at most a few KB of your answer and keep none of it beyond the 500 characters above.
  • Your signing secret is kept encrypted and never shown again. Lost it? Delete the endpoint and add it again.