> For the complete documentation index, see [llms.txt](https://docs.stopbot.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stopbot.net/v2/service-guides/stopbot-v2/blocker-v2/wp-plugins.md). # WP Plugins 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.