Frequently Asked Questions

WebDecoy is an AI bot detection and mitigation platform built on sensors with deliberately different blind spots: honeypot decoys that real visitors have no reason to touch, Bot Scanner for behavioral analysis and headless browser detection, and a Cloudflare edge sensor that catches the crawlers which never run JavaScript at all. Every detection resolves to a persistent actor identity that survives IP rotation, and you decide what happens next: block, redirect, revoke clearance, or poison the response.

Setup takes about 5 minutes. Create a WebDecoy account, add a decoy link to your website, or configure your own domain with a DNS record (CNAME or A record) for seamless integration. You'll start detecting bots instantly.

No. WebDecoy is designed for non-technical users. We provide step-by-step guides, and our simple dashboard makes everything point-and-click. If you need help, our support team is here.

Yes. Free includes 5,000 stored events per month, one property, seven days of detailed history, and continuous local and edge detection. It has no time limit and requires no credit card.

Absolutely. Every workspace starts on Free. A one-time 14-day paid-capability trial begins only after WebDecoy verifies your first real installation, so setup does not consume the evaluation period. Paid plans also have a 30-day money-back guarantee.

Bot Scanner is WebDecoy's behavioral analysis engine that detects headless browsers (Puppeteer, Playwright, Selenium), automation frameworks, and AI crawlers in real time. Unlike honeypots that wait for bots to click links, Bot Scanner actively analyzes visitor behavior, TLS fingerprints (JA3/JA4), and interaction patterns, and combines them into a threat score.

Bot Scanner analyzes multiple signals: mouse movement entropy (real humans have natural, unpredictable movements), interaction timing patterns, TLS fingerprints, WebGL/Canvas fingerprints, and browser API behavior. These signals are combined to create a threat score. Headless browsers and automation tools produce distinctive signatures that humans cannot replicate.

Bot Scanner looks for Puppeteer (including the stealth plugin), Playwright, Selenium, Nightmare, WebDriver, Phantom.js, and other headless browser frameworks. No detector catches every evasion technique, which is why WebDecoy pairs behavioral signals with decoys and the edge sensor.

Bot Scanner scores traffic; it does not block anyone on its own. Blocking only happens through response actions or enforcement you turn on, and WebDecoy starts in monitor mode so you can review what would have been blocked first. Verified search engines (Googlebot, Bingbot) are allowlisted.

Add a single script tag to your page, pointing at https://cdn.webdecoy.com/bot-detection/v1/bot-detection.min.js with your property and scanner IDs. Installation takes less than 5 minutes. The script is about 10KB gzipped and loads asynchronously. If you would rather detect on the server, install the @webdecoy/node SDK instead.

Bot Scanner detections can feed your response actions: revoke a bot's session clearance so it stays locked out on every IP it rotates to, block the actor or its IP at your WAF (Cloudflare, AWS WAF), send a webhook or email, and forward events to Slack or your SIEM (Splunk, CrowdStrike LogScale, Datadog). Decoys can also serve poisoned data or redirect. Start in monitor mode and review what would have happened before you enforce.

Because a JavaScript-only install cannot see them. The page tag identifies crawlers by reading navigator.userAgent, which requires a JavaScript runtime. Googlebot's crawl pass is a plain HTTP fetch with no DOM, and GPTBot, ClaudeBot, CCBot and PerplexityBot never execute JavaScript at all. This is a structural limit of browser-side detection (ours or anyone’s), and it is exactly what the edge sensor fixes. Install it on Cloudflare in one click and the crawl pass starts showing up straight away, with no bait to place and nothing to tune.

A Cloudflare Worker that runs in front of your origin, sees the raw HTTP request, and forwards only bot-like traffic to WebDecoy. It catches everything that never opens a browser: Googlebot's crawl pass, GPTBot, ClaudeBot, CCBot, PerplexityBot, ByteSpider, curl, and scripted HTTP clients. Install it in one click from Integrations → Cloudflare, or deploy it yourself from github.com/WebDecoy/edge Opens in a new tab . It complements the page tag rather than replacing it. See the edge sensor page for the full coverage matrix.

No. The origin response is returned unconditionally, and the detection beacon runs inside ctx.waitUntil() so it is never awaited on the response path. Every code path is wrapped in try/catch, the beacon carries a hard timeout, and a config fetch failure serves stale config rather than disabling anything. The adversarial test suite asserts that ingest returning a 500, timing out, and failing DNS each leave the response untouched, and that a throw inside the filter still serves the origin response.

The installer provisions negating routes alongside the main route. A Cloudflare route with no script attached negates less specific patterns, and the most specific pattern wins. The default set covers static prefixes for Astro, Next, Nuxt, SvelteKit, Vite, Hugo and WordPress, and you can add your own. Workers is available on the Cloudflare Free plan at 100,000 requests per day. Cloudflare Pages sites can use _routes.json instead, where excluded paths never invoke the Function at all.

The install refuses and names the conflicting pattern and script. Cloudflare runs only one Worker per matched route, so silently taking the route would stop your code from running. That is not our call to make. If the existing Worker is a hand-deployed WebDecoy one, the installer offers to adopt it instead, with explicit confirmation of what changes. Installing onto a DNS-only (grey-cloud) zone is also refused before anything is written, because Worker routes only fire on proxied records and would otherwise silently never run.

By published IP ranges and forward-confirmed reverse DNS: the primary path, and the method Google itself recommends for verifying Googlebot. WebDecoy loads the range lists Google, Bing, OpenAI, Perplexity, Apple and DuckDuckGo publish, refreshing them regularly, and degrades a verdict to unverified rather than false-verifying if that data goes stale. For rDNS, a matching PTR record is not enough: the hostname must resolve back to the source IP, and matching happens on dot boundaries, so a record like fake.googlebot.com.evil.net cannot pass. Crawlers forging Googlebot from datacenter and VPN hosts are caught by exactly this check.

Web Bot Auth is a profile of RFC 9421 HTTP Message Signatures for automated clients, defined in IETF drafts authored at Cloudflare and Google. Operators publish public keys at a well-known path on a domain they control, and their bots sign each request. WebDecoy verifies those signatures in the detection pipeline, at the edge validator, and locally inside the Node SDK. Adoption is still early, and we would rather say so than oversell it: most automated traffic carries no signature yet, and Googlebot does not sign. Google's guidance is to verify it by IP range and reverse DNS instead. Treat signature verification as the layer that strengthens as operators adopt it, not the one doing the work today.

It is a detection class that only becomes possible once verification exists. When a request claims an identity that can be checked and that check fails, the request is caught in a lie rather than merely looking suspicious. WebDecoy floors the actor's threat score at tripwire grade and marks it spoofed, the same weight it gives a honeypot hit. A legitimate crawler that simply doesn't sign yet degrades to "claimed" and is never accused.

Session clearance used to answer one question: has this session tripped a decoy? It now carries a trust level (clean, human-likely, or attested-human) plus the evidence that earned it, and a protected route can require a minimum. human-likely comes from browser-integrity checks at the interstitial or interaction cadence that reads as a real hand; attested-human comes from a third-party attestation such as a Cloudflare Turnstile verdict. Evidence only ever raises a grade, and a high threat score caps it.

No. An absent claim reads as clean, exactly what every visitor received before graded trust existed. Sessions with sparse interaction (keyboard-only navigation, assistive technology, browsers that suppress canvas or WebGL) are unscored rather than scored badly, because behavioral signals must never become an accessibility barrier. Evidence can only lift a token, never lower it.

No. Cloudflare exposes verified-bot categories on its own zones, and relying on that would restrict verification to Cloudflare customers. WebDecoy verifies Web Bot Auth signatures itself in the ingest pipeline, in the edge validator, and locally in the Node SDK, so the same verification runs wherever you deploy. The Go implementation behind it is open source at github.com/WebDecoy/web-bot-auth Opens in a new tab under Apache 2.0.

It states how many attributable AI pages were crawled for every visitor returned by a known AI platform. It is not a conversion rate, does not establish that a crawl caused a referral, and is not a benchmark. Because referral counts are a floor, the ratio is an upper bound rather than a precise measurement. See AI Traffic.

A referral is counted from a known AI-platform Referer, or from a recognized campaign tag when Referer is absent. Both signals can be omitted, so referrals remain a floor and the crawl-to-referral ratio remains an upper bound. A site can show zero referrals while AI tools are actively citing it.

Google, Microsoft, and Apple use one crawler for both a search engine and an AI product, so those crawls cannot be attributed to either side. Search referrals are outside AI Traffic by definition. These operators may show crawling with no AI referrals in this view even while their search engines send real traffic, so WebDecoy does not describe them as sending no traffic.

It is a frozen snapshot generated from AI Traffic, not a live dashboard. A report can be private or public, switched either way without changing its stable address, and optionally published without naming the site. Access is revocable by making it private, and deletion is permanent.

Pages cited is the number of distinct pages an AI platform linked someone to. That link is observable when the visit reaches your site with the necessary referral data. Whether a model's answer cited you is not observable from your own logs because it happens inside the model and leaves no trace there.

AI Journey Insights helps you investigate an actor’s likely collection targets and access patterns. Open Actors → Journey to see AI classifications alongside measured breadth, concentration, and timing. Expand the findings to inspect matching requests and their detection details.

It analyzes a sample of up to the latest 48 stored requests for an eligible actor and selected property when you open the journey. The panel shows its coverage and reuses saved results. It does not change threat scores or enforcement decisions; unclear patterns remain undetermined.

See how two observed journeys revealed concentrated repeat requests and broad coverage in our AI Journey Insights launch post.

WebDecoy's registry covers 186 known agents, including GPTBot (OpenAI), ClaudeBot (Anthropic), PerplexityBot, Googlebot, Bingbot, Applebot, and many others. Bot Scanner adds behavioral detection for headless browsers and automation frameworks.

Decoy links are invisible honeypot links placed on your website. They're hidden from real users but visible to web crawlers and AI bots. When a bot visits a decoy link, we detect it and can take action.

No. New WebDecoy accounts come with a working honeypot URL on our shared domain the moment you sign up: no DNS records, no certificates, no setup. You can create as many decoys as you want this way. Custom domains are an optional upgrade for when you'd rather host decoys under your own brand.

Custom domains are an optional upgrade: decoys work out of the box on our shared domain without any DNS setup. When you want decoys hosted under your own hostname, add a CNAME or A record pointing to WebDecoy in your DNS provider. We provision a Let's Encrypt SSL certificate automatically. Example: decoys.yoursite.com → webdecoy.com

Yes. You have several options: revoke the bot's session clearance so it stays locked out on every IP it rotates to, block the actor or its IP address at your Cloudflare or AWS WAF with rules that expire, return HTTP 403 Forbidden, redirect to custom pages, or return intentionally bad data to poison their training. Blocking is something you turn on; WebDecoy starts in monitor mode.

No. Decoy links are invisible and don't impact your site's performance. WebDecoy uses edge computing for bot detection, ensuring instant responses without slowing down your site.

Endpoint Decoys are API honeypots: fake API endpoints that detect malicious traffic. Unlike link decoys for web scrapers, Endpoint Decoys catch credential stuffing, SQL injection, API enumeration, and other backend attacks. Real users have no reason to call an endpoint that doesn't exist.

Endpoint Decoys automatically detect and categorize: SQL injection (critical), command injection (critical), XXE attacks (critical), XSS (high), path traversal (high), insecure deserialization (high), and mass assignment (medium). Each attack is logged with full forensic data.

Yes. WebDecoy maps each detection to a MITRE ATT&CK tactic. For example, web crawler detection maps to Reconnaissance (TA0043), credential stuffing maps to Credential Access (TA0006), and path or API probing maps to Discovery (TA0007). You can see the tactic on the detection in the dashboard and through the API.

WebDecoy's decoys see activity that falls under techniques such as T1595 (Active Scanning), T1594 (Search Victim-Owned Websites), T1110 (Brute Force), and T1083 (File and Directory Discovery). Each detection carries a MITRE tactic; webhook and SIEM payloads are compact and do not include technique IDs, so fetch the detection from the API by its ID for the full mapping.

Yes. Our REST API lets you programmatically create decoys, query detection events, manage webhooks, and configure settings. Full API documentation is available in your dashboard.

Yes. Set up webhooks to receive a signed JSON event when bots are detected, send alerts to Slack, or use the email response action. Webhooks can point at any HTTPS endpoint you control.

WebDecoy works behind any CDN. It has enforcement integrations for Cloudflare, AWS WAF (including CloudFront), Fastly, Vercel and Netlify. For decoys on your own hostname, WebDecoy provisions a Let's Encrypt certificate automatically.

Yes. You can query detections through the REST API, and forward detection events to webhooks or your SIEM. Instead of an email per detection, WebDecoy sends a periodic digest.

No. WebDecoy does not offer SAML SSO. Sign-in is handled by Auth0.

Yes. Create Endpoint Decoys at paths like /api/admin/login, /api/users, or /graphql to catch attackers probing your API. Configure expected content types, allowed HTTP methods, and enable request body capture for forensic analysis.

Yes. Endpoint Decoy detections are forwarded like any other detection: to Splunk (HEC), CrowdStrike Falcon LogScale, or Datadog Logs through the native integrations, or to any other SIEM, such as Elastic, through a webhook. SIEM payloads carry the detection ID, so you can fetch full forensic detail from the API.

Yes. WebDecoy has a hosted MCP (Model Context Protocol) server at https://mcp.webdecoy.com/mcp. Connect Claude Code, Claude.ai, Claude Desktop, ChatGPT (developer mode), Codex, or any assistant that runs local MCP servers through the WebDecoy CLI. Ask it to install WebDecoy in your app with the right package and code for your stack, confirm the install is reporting, and ask whether protection is actually enforced, which bots were seen (including forged crawlers), what an actor did, and what your policy is configured to do. It is available on every plan, including Free. Read the setup guide Opens in a new tab or the announcement.

Only what you allow. You sign in with your WebDecoy account over OAuth, with no API key to copy, and choose which sites each assistant may see. Access is read-only by default. The setup tools (add a site, create decoys and a site’s script tag, check a page serves the tag) work only if you tick “Also allow setup”, and count toward your plan’s limits. An assistant can never change policies, enforcement, settings or billing, and never receives secret keys. You can review or disconnect any assistant in Settings, Connected apps.

We store bot detection events, and those include personal data under GDPR: IP addresses, user agents, request headers, and bot fingerprints used to correlate an actor across rotating IPs. We process them as your processor under our DPA. See our Privacy Policy for complete details.

Detection data is encrypted in transit, with TLS required on every endpoint that receives it, and storage is encrypted at rest by our infrastructure providers. Access to production is limited to the people who need it, and data is separated by organization. WebDecoy does not hold SOC 2 or ISO 27001 certification and has not been independently audited. Our DPA lists the measures we actually apply.

All webhooks are signed with HMAC-SHA256 in the X-WebDecoy-Signature header. Verify the signature using your webhook secret to ensure the request came from WebDecoy. Each event is delivered once; there are no automatic retries.

Detection data is stored in a managed database run by our infrastructure provider. We do not offer an uptime SLA.

Yes. Email [email protected] and we delete your organization and the personal data associated with it within 30 days, and confirm in writing. Aggregate counts that contain no personal data, and records the law requires us to keep (such as billing), may be retained. See our Privacy Policy and DPA.

We accept all major credit cards (Visa, Mastercard, American Express), bank transfers, and wire transfers for enterprise customers. Payments are processed securely through Stripe.

Yes. Upgrade or downgrade at any time. Changes take effect immediately, and we'll prorate charges or issue refunds based on your billing cycle.

Yes. Save 20% with annual billing. Contact us if you manage many sites; the Agency plan pools volume across a portfolio.

30-day money-back guarantee on all paid plans. If WebDecoy isn't right for you, we'll issue a full refund. No questions asked.

Free includes documentation. Starter includes email support. Pro and Agency include priority support.

First, make sure the decoy URL is accessible from the internet. Check that robots.txt isn't blocking it and that you're not blocking WebDecoy's detection crawler. Contact support if you need help.

Check that your webhook endpoint is accessible from the internet and returns a 2xx response within 10 seconds. Each event is delivered once, with no automatic retries; a non-2xx response or a timeout is recorded as a failed delivery on the webhook's stats in your dashboard.

Yes. Add decoy links in your HTML, load them dynamically with JavaScript, or use our API to manage decoys programmatically. Works great with React, Vue, Angular, etc.

Yes. You can place decoy links anywhere on your site - root, subdirectories, or specific paths. They'll work regardless of your URL structure.

Log in to your account and go to Settings → Billing. You can update payment methods, email address, and billing information anytime.