Your Next.js page loads. The next useful check is whether a test request produces a record you can inspect in your bot dashboard.

This walkthrough installs WebDecoy’s Vercel entry point, sends one labeled request, and shows how to verify delivery before changing an enforcement policy. We build WebDecoy. The downloadable example uses Next.js 16.4.6 and the published WebDecoy 0.23.0 packages.

Download the complete Next.js example. It includes the request hook, a small diagnostic page, an inspection endpoint and local checks. Use your own WebDecoy API key for dashboard reporting.

Watch the 25-second live setup proof

Watch on YouTube. The silent clip includes English captions and animates the verified HTTP response and dashboard fields. It is a controlled setup test, not a screen recording or a real AI crawler visit.

We deployed the example to Vercel and sent a labeled request to /api/inspect at 16:44 UTC on November 13, 2026. It returned HTTP 200 with reportingConfigured: true, decision: "block" and wouldBlock: "true". The matching SDK → Test record in the dedicated demo property showed Logged, not blocked. Monitor mode kept serving the request while reporting its decision.

That verifies reporting for this request. Follow the steps below to confirm the same result in your own deployment.

1. Install the Vercel adapter

For a Next.js app hosted on Vercel:

npm install @webdecoy/[email protected] @webdecoy/[email protected]

Next.js 16 calls this request hook proxy.ts. Place it beside app, or beside src/app if your project uses src:

import webdecoy from '@webdecoy/nextjs/vercel';

export default webdecoy;

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Import the function and then export it as shown. Keep config in this file so Next.js can analyze the matcher. In Next.js 13–15, use middleware.ts instead. Existing projects should integrate with their authentication and redirect hook; do not overwrite that file or install both conventions.

The matcher includes page and API routes while excluding the named Next.js assets. Adjust it for other static assets your project serves. A request outside the matcher cannot verify this installation.

For Astro, SvelteKit and other Vercel frameworks, use the separate @webdecoy/node/vercel setup. The Next.js example above is not a universal framework file.

2. Enable reporting with a server-side API key

Create an API key for the intended site in your WebDecoy account. In Vercel, add WEBDECOY_API_KEY under the project’s environment variables and deploy again. Select the environment you actually intend to test: a production variable is not automatically evidence that a preview deployment has it.

When running the download locally:

npm ci
cp .env.example .env.local
# Set WEBDECOY_API_KEY in .env.local, then:
npm run dev

The example listens on http://127.0.0.1:3107. Keep the key on the server. Do not use a NEXT_PUBLIC_ prefix, paste it into a component or commit the environment file.

Reporting and clearance use different credentials. The API key turns on detection reporting. WEBDECOY_SITE_KEY, WEBDECOY_SCANNER_ID and WEBDECOY_SENSOR_KEY configure the clearance gate. This walkthrough does not add those gate credentials. If you already configured a gate, review its site mode and protected paths separately.

Without the reporting key, this Vercel entry point does not report detections. Local-only rules are available through the ordinary SDK adapters and the Express browser playground; that is a different setup.

3. Send a labeled test to your app

In the downloaded example:

curl -i -A 'WebDecoy-Test/1.0' \
  http://127.0.0.1:3107/api/inspect

For a deployed project, replace the origin with your own domain:

curl -i -A 'WebDecoy-Test/1.0' \
  https://your-site.example/api/inspect

Use an existing matched page if you added the adapter to your own app rather than the example. You do not need to create the diagnostic endpoint to report a detection.

Detection starts in monitor mode. A request that would be refused can still reach your route. The example’s endpoint shows whether a reporting key is configured and whether the middleware forwarded a decision. It does not expose the key or claim that the dashboard received the request.

4. Confirm the record in WebDecoy

Open Detections for the site associated with the key. Find a record labeled Test, then match the requested path and time to the request you just sent. The reserved user agent exercises the reporting path; it is not a real AI crawler visit or evidence of detection accuracy.

Use this sequence to identify a gap:

What you seeWhat to check next
Page loads, but no key is configuredAdd the server-side key to the correct environment and restart or redeploy.
Key configured, but no middleware verdictCheck the matcher, request-hook export, runtime logs and whether the request reached this deployment.
Request has a verdict, but no matching Test recordConfirm the key’s site, dashboard time window and reporting errors. A response alone is not a delivery receipt.
Login page, preview challenge or upstream refusalUse the deployment’s authorized access path. A request stopped upstream cannot test the app hook.
Test record with matching path and timeReporting is verified for that request. Next, inspect actual traffic.

WebDecoy forwards x-webdecoy-decision, x-webdecoy-detection-id and x-webdecoy-would-block to the application when detection runs. These are request headers for your code, not necessarily response headers visible in curl -i. The example deliberately exposes only the decision and would-block value through its diagnostic endpoint.

5. Read crawler activity and referrals separately

As real traffic arrives, inspect a few detections: requested paths, claimed crawler names, available identity evidence and repeated activity. A client can copy a familiar user agent. Keep claimed and verified identities distinct.

The middleware’s detections are not a complete access log. It sees requests that reach it and match its scope; upstream refusals and paths outside that scope are absent. Do not infer complete coverage of a hosting cache or the whole Vercel edge network from these records.

Then open the relevant AI traffic reports for your site. Crawler activity describes content requests. AI referrals describe visitor arrivals with identifiable attribution from assistants. This server middleware setup does not itself establish browser-side referral collection. Configure that collection separately when you need the referral view; missing referrer data cannot be recovered merely by adding middleware.

The AI traffic hub explains which record answers which question. WebDecoy can add application evidence alongside Cloudflare and other edge controls you already use.

What we checked in this example

The downloadable project’s production build passed. Its local HTTP checks established:

  • The actual Next.js app served ordinary and reserved test requests without an API key and correctly showed no configured reporting key or received verdict.
  • The published core Vercel middleware sent test_trigger through real HTTP to a local API fixture, continued in monitor mode, and forwarded the fixture’s decision.
  • Client-supplied verdict headers did not replace the middleware’s result.

The local fixture is labeled as such in the example and its tests. Separately, the live Vercel test summarized above produced a matching SDK Test record in WebDecoy. Its source, reserved user agent, /api/inspect path and timestamp matched the request. The record explicitly showed that it was logged without blocking and was not eligible for automatic action.

A reserved test trigger verifies the reporting path; it does not establish detection accuracy against real AI crawlers or coverage of requests that never reach the middleware. Repeat step 4 with your own deployment and key.

Download and run the example, or inspect the Node SDK and framework adapters. Start with a visible test record, then decide which traffic needs investigation or an enforcement policy.

Frequently Asked Questions

Can I see AI crawler traffic on Vercel without blocking visitors? +

The WebDecoy Vercel entry point starts detection in monitor mode. With an API key, eligible bot detections report to your dashboard while requests continue. A separately configured clearance gate follows the site's policy; review it independently.

Does an HTTP 200 prove WebDecoy installed correctly? +

No. Monitor mode serves requests, and missing credentials or reporting failures can also leave the page working. Send the reserved test request, then confirm its Test record, path and timestamp in your own dashboard.

Will this middleware show every AI visit or referral? +

No. It observes requests that reach the middleware and match its scope. Detections are not a complete access log, names can be spoofed, and AI referral collection is separate from crawler observation.

Continue your investigation

  1. Understand crawler and referral reports

    Keep requested pages, claimed identities and attributable visitors separate.

  2. Choose your installation path

    Use the adapter that matches your framework and hosting environment.

  3. Investigate traffic that reaches your app

    Connect application evidence to the edge controls you already use.

Want to see WebDecoy in action?

Get a personalized demo from our team.

Request Demo