WP Plugins

This guide explains how to install the plugin, connect it to a Blocker V2 configuration, test the connection, enable protection, and review visitor logs.

Use the Stopbot WordPress plugin to protect public WordPress frontend page requests with the Blocker V2 endpoint, without adding custom code to your theme or plugin files.

Endpoint Used

GET https://api.stopbot.net/services/blockerv2

The plugin only uses the Blocker V2 endpoint.

How It Works

1. A visitor opens a public WordPress frontend page.

2. WordPress runs the Stopbot plugin before rendering the page.

3. The plugin sends the visitor IP, user agent, current URL, and enabled request data to Stopbot.

4. Stopbot returns the Blocker V2 decision.

5. The plugin follows the response when blockAccess is 1.

The plugin does not check WordPress admin, login, AJAX, cron, REST, XML-RPC, or static asset requests. This helps reduce lockout risk and prevents checks from being triggered by images, CSS, JavaScript, and favicon requests.

Requirements

Requirement	Description
WordPress	Version 5.8 or newer
PHP	Version 7.4 or newer
Stopbot API key	A valid API key from your Stopbot account
Blocker V2 configuration	A configuration name created in the Stopbot panel

Before You Install

Prepare these values first:

Value	Where To Get It
API key	Stopbot panel account/API key page
Configuration Name	Stopbot panel, Services, Blocker V2

The configuration name must match the Blocker V2 configuration exactly. If the name is different, the API will not be able to load the intended rules.

Installation

Official plugin download:

https://panel.stopbot.net/stopbot.zip

Source code:

https://github.com/stopbot-net/Stopbot-Wordpress-Plugin

Install the plugin using one of these methods:

Method	Steps
Official zip upload	Download https://panel.stopbot.net/stopbot.zip, open WordPress Admin, go to Plugins, Add New, Upload Plugin, choose the .zip, then activate it
GitHub source	Open https://github.com/stopbot-net/Stopbot-Wordpress-Plugin, download or clone the source, package it as a stopbot folder, then upload it to WordPress
WordPress admin upload	Upload a Stopbot plugin .zip from a trusted source, then activate it
Manual upload	Upload the stopbot folder to /wp-content/plugins/, then activate Stopbot from WordPress Admin
WordPress Plugin Directory	Search for Stopbot from Plugins, Add New, then install and activate it when the listing is available

After activation, open:

Settings > Stopbot

Setup Wizard

The setup wizard helps complete the first configuration.

Step	Action
Create Blocker V2 Configuration	Create or open a Blocker V2 configuration in the Stopbot panel
Connect API Key	Paste your Stopbot API key into the plugin
Test Connection	Confirm WordPress can reach the Blocker V2 endpoint
Enable Protection	Turn on protection after the connection test succeeds

The connection test uses one Blocker V2 API request.

Main Settings

Open the Main tab and configure:

Setting	Description
Enable Protection	Turns frontend checking on or off
API Key	Your Stopbot API key
Configuration Name	The exact Blocker V2 confname from the Stopbot panel
Trust Proxy Headers	Uses proxy visitor IP headers when the site is behind a trusted proxy
Request Data	Sends safe request parameters and headers for Blocker V2 parameter/header rules
Path Rules	Controls which frontend paths are checked

Click Save & Test Connection first. Enable protection only after the test succeeds.

Path Rules

Use Path Rules when you want to control which WordPress frontend paths are checked.

Mode	Behavior
Exclude listed paths	Checks all frontend pages except the listed paths
Only check listed paths	Checks only the listed paths

Use one path per line.

Example:

/thank-you/
/checkout/order-received/
/landing/safe-page/

Path Rules are also useful when a Blocker V2 redirect target points back to a WordPress page that should not be checked.

Redirect Loop Protection

When Stopbot returns pageResponseType: RedirectURL, the plugin redirects the visitor to pageResponseContents.

To help prevent ERR_TOO_MANY_REDIRECTS, the plugin skips the redirect action when the redirect target points to the same page as the current request. It compares the page without query strings, normalizes repeated or trailing slashes, and treats HTTP and HTTPS as the same page for this check.

For pages that should never run protection, add them to Path Rules with Exclude mode.

Admin Tab

Use the Admin tab to control logged-in user bypass.

Setting	Description
Logged-In Users	Bypass checks for logged-in WordPress users
Role	Bypass only selected roles when roles are selected

By default, logged-in WordPress users are bypassed to reduce administrator lockout risk.

To test the plugin as a visitor, open the website in an incognito/private browser window, log out first, or temporarily disable logged-in user bypass.

Visitor Log

The Visitor Log tab shows recent Stopbot checks from a local WordPress database table.

Available columns:

Column	Description
Date & Time	Time the check was recorded
IP Address	Visitor IP used for the check
Country	Country returned by Stopbot
ISP	ISP returned by Stopbot
Hostname	Hostname returned by Stopbot
Device	Device detected from the user agent
OS	Operating system detected from the user agent
Browser	Browser detected from the user agent
Desc	Stopbot detectActivity result
Accepted	Yes when blockAccess is 0
Threat	Stopbot threatURL result
Status	API connection status and HTTP response code

Visitor Log supports:

• 10, 25, 50, or 100 results per page.

• Sorting by Date & Time.

• Sorting by IP Address.

• Filters for Device, OS, Browser, Country, ISP, and Desc.

• Automatic refresh every 60 seconds while the settings page is open.

• Statistics by Device, OS, Country, and Browser.

• A graph for blocked, accepted, and total checks.

The plugin creates a dedicated WordPress table for visitor logs during activation and removes it when the plugin is uninstalled. It does not store API keys or full page URLs in the visitor log.

Diagnostic Log

Use the Log tab only when debugging.

Diagnostic Log can help identify connection issues, invalid JSON responses, blocked requests, or configuration problems. API keys are not written to the diagnostic log.

For busy production sites, keep Diagnostic Log off unless you are actively troubleshooting.

Proxy Headers

Only enable proxy headers when the site is always behind a trusted proxy, such as:

• Cloudflare

• Nginx reverse proxy

• Apache reverse proxy

• Caddy reverse proxy

• Load balancer

Set this option to "Off" for normal hosting or when you are not sure.

If proxy headers are enabled on a public origin without a trusted proxy, visitors may spoof their IP address using headers such as X-Forwarded-For.

Use this simple rule:

Site Setup	Proxy Headers
Cloudflare is active and the origin only accepts Cloudflare traffic	Enable
A trusted reverse proxy controls the real visitor IP header	Enable
Normal hosting or unsure	"Off"

Response Handling

The plugin follows the Blocker V2 response.

Response Field	Behavior
blockAccess: 0	Visitor is accepted
blockAccess: 1 with RedirectURL	Visitor is redirected to pageResponseContents
blockAccess: 1 with HTTPStatusCode	WordPress returns the configured HTTP status code

Always use blockAccess as the final access decision. Do not use isBot as the final block decision. isBot describes visitor classification, while blockAccess tells the integration whether the configured page response must be applied.

Testing Checklist

After setup:

1. Save the API key and Configuration Name.

2. Click Save & Test Connection.

3. Enable protection only after the test succeeds.

4. Purge WordPress, server, and CDN cache once.

5. Open the website from an incognito/private browser window.

6. Confirm the visitor appears in Visitor Log.

7. Confirm the Stopbot panel also records the visitor.

8. Test an allowed visitor and a blocked condition.

Troubleshooting

Problem	What To Check
Nothing appears in Visitor Log	Make sure Enable Protection is on, test from a logged-out/incognito browser, and purge page cache
Admin user is not checked	Logged-in users are bypassed by default
Wrong visitor IP is shown	Check Trust Proxy Headers and confirm the origin only accepts traffic from the trusted proxy
ERR_TOO_MANY_REDIRECTS	Exclude the redirect target path, or make sure Blocker V2 does not redirect to the same checked page
API test fails	Confirm API key, Configuration Name, hosting firewall, and outbound HTTPS access to api.stopbot.net
Static assets appear in logs	Update to the latest plugin version and confirm the request is a frontend page request, not an asset path

Data Sent To Stopbot

When protection is enabled, the plugin sends only the data needed for Blocker V2 checks:

Data	Purpose
API key	Authenticate the request
Configuration Name	Load the correct Blocker V2 rules
Visitor IP address	IP, ASN, ISP, hostname, geo, and threat checks
User agent	Bot, browser, OS, and device classification
Current page URL	URL threat and rule evaluation
Safe request parameters	Optional Params rules
Safe request headers	Optional HTTP Headers rules

Keep your API key private. Do not publish it in browser-only JavaScript, public repositories, screenshots, or support messages.