Headless browser detection: what it catches and how to use it

What a headless browser is

A headless browser runs the same engine as a normal one but is controlled by code. That makes it good for testing and just as good for abuse, because it runs your page scripts and can look much like a person.

Simple bots that send plain requests are easy to see. Headless browsers are the harder case, which is why a result from the browser itself is useful.

What the bot signal reports

signals.bot.result is good, bad or not_detected. For a bad bot, signals.bot.types names the kind that was seen.

• headless: a browser run without a window.
• webdriver, playwright and selenium: common automation frameworks.
• inhuman_timing and inconsistent_environment: behaviour or a setup that does not look like a person.
• A bot we recognise, such as a search crawler, is reported as good with its operator and category.

Bot detection →

Read it on your server

The browser never sees the result. Fetch the event after identify and decide on the server.

if (!/^ev_[0-9A-HJKMNP-TV-Z]{20}$/.test(eventId)) throw new Error('bad eventId'); // fail closed
const res = await fetch(`https://api.fpchecker.com/v1/events/${eventId}`, {
  headers: { 'X-Secret-Key': process.env.FPCHECKER_SECRET_KEY },
});
if (!res.ok) throw new Error('event lookup failed'); // fail closed
const event = await res.json();
if (event.eventId !== eventId || !(Date.now() - Date.parse(event.createdAt) <= 5 * 60_000)) throw new Error('stale or reused event'); // wrong or old event
if (!(await markEventUsed(eventId))) throw new Error('stale or reused event'); // your store: true only the first time
const { signals } = event;

if (signals?.bot?.result === 'bad') {
  refuseOrChallenge(); // your code
}

What to do when it fires

For a bad bot on a sign-up, a claim or a checkout, refuse or ask for a human check. For not_detected, carry on, but remember that no detection is not a guarantee. A determined attacker can try to look ordinary, so combine the result with the network signals and the device history.

If you only have a plain HTTP request and no browser script, the bot check endpoint classifies the request from your backend.

Bot check endpoint →

Do not block the good ones

Search engines and other crawlers you want are labelled good, and one that pretends to be a confirmed bot is flagged. Look at the result and the identity before you block automated traffic.

Bot directory →

Frequently asked questions