Stopbot for WordPress protects public WordPress frontend pages by checking each visitor with the STOPBOT Blocker V2 API before WordPress renders the page.
This plugin only uses the Blocker V2 endpoint:
https://api.stopbot.net/services/blockerv2
| Resource | Link |
|---|---|
| Official Download | https://panel.stopbot.net/stopbot.zip |
| WordPress Plugin Guide | https://docs.stopbot.net/v2/service-guides/stopbot-v2/blocker-v2/wp-plugins |
| GitHub Repository | https://github.com/stopbot-net/Stopbot-Wordpress-Plugin |
| Stopbot Panel | https://panel.stopbot.net/ |
| Stopbot Website | https://stopbot.net/ |
- WordPress 5.8 or newer
- PHP 7.4 or newer
- A STOPBOT account
- An active Blocker V2 configuration in
panel.stopbot.net - WordPress must be able to make outbound HTTPS requests to
api.stopbot.net
- Download the official plugin zip from
https://panel.stopbot.net/stopbot.zip, or zip the plugin as astopbotfolder from this repository. - Open WordPress Admin.
- Go to Plugins > Add New > Upload Plugin.
- Upload the zip file.
- Activate
Stopbot. - After activation, WordPress opens the setup wizard automatically.
- If it does not open, go to Settings > Stopbot.
The plugin includes a setup wizard to make installation easier for non-technical users.
The wizard checks:
| Step | What It Confirms |
|---|---|
| Create Blocker V2 Configuration | A confname is ready from panel.stopbot.net |
| Connect API Key | A valid 32-character STOPBOT API key is configured |
| Test Connection | WordPress can reach the Blocker V2 endpoint |
| Enable Protection | Frontend visitor checks are enabled |
Use Save & Test Connection after entering the API key and configuration name. The connection test uses one Blocker V2 API request.
Open Settings > Stopbot and configure:
| Setting | Description |
|---|---|
| Enable Protection | Runs Blocker V2 checks on public frontend requests |
| API Key | Your STOPBOT API key |
| Configuration Name | The exact Blocker V2 confname from the STOPBOT panel |
| API Timeout | How long WordPress waits for the STOPBOT API |
| If API Fails | Allow the visitor or return HTTP 503 when the API cannot be reached |
| Request Data | Sends safe query params and safe headers to Blocker V2 |
| Proxy Headers | Uses Cloudflare or reverse proxy visitor IP headers |
| Logged-In Users | Bypasses checks for logged-in WordPress users |
| Role | Limits logged-in bypass to selected WordPress roles |
| Path Rules | Choose whether listed paths are excluded from checks or are the only paths checked |
On public frontend page requests, the plugin sends a GET request to Blocker V2 with:
| Parameter | Source |
|---|---|
apikey |
API Key field in the plugin settings |
confname |
Configuration Name field in the plugin settings |
ip |
Visitor IP address |
ua / useragent |
Visitor user agent |
url |
Current WordPress page URL |
params |
Safe query parameters as JSON |
headers |
Safe request headers as JSON |
The plugin does not run on WordPress admin pages, AJAX, cron, JSON/REST requests, wp-login.php, wp-cron.php, xmlrpc.php, WordPress asset directories, or static asset paths such as /favicon.ico, images, CSS, JavaScript, fonts, and media files.
Use Path Rules when you need path-level control. In Exclude listed paths mode, all public frontend pages are checked except matching paths. This is useful when a Blocker V2 RedirectURL points to a page on the same WordPress site. In Only check listed paths mode, Stopbot runs only on matching paths.
Path rules support multiple lines. Use an exact path such as /2026/07/08/hello-world/, or use /* for a prefix such as /blocked/*.
The settings page is organized into four tabs:
| Tab | Purpose |
|---|---|
| Main | API, request behavior, proxy headers, and path rules |
| Admin | Logged-in user bypass and role selection |
| Visitor Log | Recent checked visitors, filters, pagination, and statistics |
| Log | Diagnostic log controls and textarea |
The plugin does not cache Stopbot API decisions. Each checked frontend page request is sent to Stopbot directly so decisions do not become stale or cross over between different URLs, user agents, query parameters, or headers.
This plugin connects to the Stopbot API service to check public WordPress frontend visitors before WordPress renders the page.
| Item | Details |
|---|---|
| Service used | https://api.stopbot.net/services/blockerv2 |
| Provider | STOPBOT.NET |
| Service website | https://stopbot.net/ |
| Documentation | https://docs.stopbot.net/v2/service-guides/stopbot-v2/blocker-v2/wp-plugins |
| Privacy Policy | https://docs.stopbot.net/information/privacy-policy |
| Terms of Services | https://docs.stopbot.net/information/terms-of-services |
Data is sent when the administrator clicks Save & Test Connection, and when Enable Protection is turned on and a public frontend page request is checked.
The plugin sends the STOPBOT API key, Blocker V2 configuration name, visitor IP address, visitor user agent, current page URL, and, when Request Data is enabled, safe query parameters and safe request headers. Stopbot uses this data to return the Blocker V2 decision, including whether the visitor should be accepted, blocked, redirected, or served a configured HTTP status response.
This plugin includes Chart.js 4.5.1 for the Visitor Log statistics graph. Chart.js is licensed under the MIT license. The runtime file is bundled at assets/js/chart.umd.js, the source file is bundled at assets/js/chart.js, and the license file is included at assets/js/chartjs-license.txt.
The Visitor Log tab stores recent Stopbot checks in a dedicated WordPress database table named with the active WordPress prefix, for example wp_stopbot_blockerv2_visitor_log. It shows date and time, IP address, country, ISP, hostname, detected device, OS, browser, detection description, accepted status, threat status, and API connection status with the API HTTP response code. It supports database sorting by date/time and IP address, plus filters for device, OS, browser, country, ISP, and description.
The table is created automatically when the plugin is activated and dropped when the plugin is uninstalled. The tab loads visitor rows by database page, supports 10, 25, 50, or 100 results per page, and refreshes the current page every 60 seconds while the settings page remains open. Its statistics graph uses the bundled local Chart.js library on the Stopbot settings page. The log does not store API keys or full page URLs. Device, OS, and browser are detected from the visitor user agent.
When Blocker V2 returns blockAccess: 1, the plugin follows the response fields:
| Field | Behavior |
|---|---|
pageResponseType: RedirectURL |
Redirects the visitor to pageResponseContents |
pageResponseType: HTTPStatusCode |
Returns the configured HTTP status code |
| Missing or unsupported page response | Returns HTTP 403 |
If pageResponseContents points to the same page as the current request, the plugin skips that single redirect to prevent a browser redirect loop. The comparison ignores query strings, treats HTTP and HTTPS as the same page, and normalizes repeated or trailing slashes in the path.
If the API cannot be reached, the plugin follows the If API Fails setting.
Enable Trust Cloudflare / reverse proxy visitor IP headers only when the WordPress site is always behind a trusted proxy such as Cloudflare, Nginx, Apache, Caddy, or a load balancer that controls CF-Connecting-IP, X-Real-IP, or X-Forwarded-For.
Set this option to "Off" when the site is installed on normal hosting, or when you are not sure whether a trusted proxy is in front of WordPress.
Use this simple rule:
| Site Setup | Proxy Headers |
|---|---|
| Cloudflare is active and the origin server only accepts Cloudflare traffic | Enable |
| Nginx, Apache, Caddy, or a load balancer is forwarding the real visitor IP | Enable |
| Normal shared/VPS hosting without a controlled reverse proxy | "Off" |
| Not sure | "Off" |
If this option is enabled on an untrusted public origin, visitors may spoof their IP address by sending fake headers such as X-Forwarded-For.
By default, logged-in WordPress users are bypassed to reduce administrator lockout risk. When testing protection, use an incognito/private browser window, log out first, or temporarily disable the logged-in user bypass.
- Do not commit API keys to a public repository.
- Do not expose the API key in frontend JavaScript.
- The plugin removes cookies, authorization headers, CSRF tokens, and WordPress nonce headers before sending header data to STOPBOT.
- The plugin removes common sensitive query parameters such as passwords, tokens, nonces, and API keys before sending params JSON.
| Issue | What To Check |
|---|---|
| Visitors are not checked | Confirm Enable Protection is on, API key is valid, confname is filled, and you are not testing from a logged-in WordPress session that is bypassed |
| Everyone is allowed | Check API failure behavior and confirm WordPress can reach api.stopbot.net |
| Wrong visitor IP | Enable proxy headers only when the site is behind a trusted proxy |
| Admin user is not checked | This is expected when logged-in user bypass is enabled. Test from an incognito/private window or disable the bypass temporarily |
| API is not called on cached pages | Purge existing full-page cache, then exclude protected pages from server/CDN cache if needed |
| Static assets appear in STOPBOT logs | Update to the latest plugin version and purge cache. Asset paths such as /favicon.ico, images, CSS, JavaScript, fonts, and media files are skipped by the plugin |
| Unexpected redirects | Review the Blocker V2 page response settings in the STOPBOT panel |
| ERR_TOO_MANY_REDIRECTS after redirecting to an internal WordPress page | Update to the latest plugin version. Same-page redirect loops are skipped automatically. For landing pages that should never be checked, use Path Rules with Exclude listed paths |
| Redirect does not happen but visitor appears in STOPBOT logs | Enable Diagnostic Log, reproduce the request, then check the log textarea for blockaccess, responsetype, redacted response URL, and redirect/status fallback entries |
Important: the plugin runs during WordPress frontend rendering. When protection is enabled and configured, the plugin asks WordPress cache plugins to avoid full-page caching by setting no-cache flags and headers. The plugin also attempts to purge common WordPress cache plugins on activation and settings save. If a page was already cached by server/CDN cache outside WordPress, purge LiteSpeed/server/CDN cache once so WordPress can execute the protection hook on the next request.