WHMCS integration: cPanel & Plesk

This integration works with HSPs, Resellers, and Marketplaces.

Blackwall provides an integration for the WHMCS billing and automation platform that works with cPanel and Plesk hosting panels. This integration enables hosting providers to manage Blackwall bot management and protection services via WHMCS.

During installing the plugin, the WHMCS administrator can create bespoke Blackwall packages by selecting the product components and component functions to include, based on the required service level, customer needs, and budget.

When a package is then assigned to a customer account, the corresponding Blackwall components and features are made available to the customer. The customer can access and configure only the Blackwall features made available through their assigned package.

Use the following instructions to configure and manage the Blackwall WHMCS integration for cPanel and Plesk:

Requirements

An existing Plesk or cPanel server with the Blackwall Protection plugin installed and configured, as per our Plesk documentation and WHM-cPanel documentation.
The Blackwall plugin is installed on the WHMCS server, as per our WHMCS documentation
A WHMCS account with associated administrator permissions.

Configure the plugin

To configure the plugin, perform each of the following sub-steps:

Add the Blackwall server

Log in to your WHMCS account using your login credentials.
Once your account homepage loads, from the top-right corner of the WHMCS admin panel, click .
From the options displayed, select System Settings.
In the search field on the System Settings page, enter 'server'.
Click the Servers widget.
Click Add New Server.
On the basic server form displayed, confirm that Blackwall is selected.
Enter your GateKeeper API hostname (without https://).
Leave the Username and Password empty.
Enter your GateKeeper API key (UUID) in the Access Hash field.
Click Test Connection to verify that the credentials entered are correct. If the information entered in the previous steps is correct, a success message displays.
Click Continue once you have seen the success message.

Create a WHMCS Server Group

Repeat steps 1-5 of the previous section.
Click Create New Group.
.
Enter a meaningful name for your new group in the Name field.
Select your new Blackwall server from the left list panel and click Add to move it to the right list panel. This effectively adds the server to your new group. You can remove a server again by clicking it in the right-hand list panel and clicking Remove, which effectively removes the server from your new group. For this plugin, only one server (GateKeeper instance) should be associated with any server group.
Click Save Changes.

Add cPanel or Plesk server

Log in to your WHMCS account using your login credentials.
Once your account homepage loads, from the top-right corner of the WHMCS admin panel, click .
From the options displayed, select System Settings.
In the search field on the System Settings page, enter 'server'.
Click the Servers widget.
Click Add New Server.
On the basic server form displayed, confirm that cPanel or Plesk is selected.
Enter your cPanel or Plesk server hostname (without https://).
Either populate the Username and Password fields and skip the next step.
Or, enter your cPanel or Plesk instance's API key (UUID) in the API Token field.
Click Test Connection to verify that the credentials entered are correct. If the information entered in the previous steps is correct, a success message displays.
Click Continue once you have seen the success message.
On the Add Server configuration page that displays, scroll to the Server Details panel.
In the Gatekeeper Server dropdown field, select the Gatekeeper server that you previously added in Add the Blackwall server
Then click Save Changes. Once changes are saved here, your Plesk or cPanel plugin state switches from standalone to managed_by.

Warning

When the extension is in managed_by mode, automatic hosting panel event hooks for GateKeeper domain registration and DNS updates are disabled. This includes events such as creating or deleting hosting accounts and subdomains in cPanel or Plesk.

Register domains and apply DNS updates through your external provisioning flow, such as WHMCS, and use the extension CLI commands update-domain-dns and reset-domain-dns where required.

Use standalone mode if you want cPanel or Plesk to handle domain registration and DNS updates automatically in response to hosting events.

Create new product

You can create a new product by performing the steps contained in the WHMCS documentation, or skip this section if you want to use an existing product.

Create Blackwall Addon

Log in to your WHMCS account as an administrator, using your login credentials.
Once your account homepage loads, from the top-right corner of the WHMCS admin panel, click wrench icon and then System Settings.
Click the Product Addons widget.
At the top of the page displayed, click the + Add new Addon button.
On the Create New Addon page that displays, perform the following instructions:
1. Make sure that the Independent Product widget is selected.
2. In Product Name, enter the customer-facing name of the product. This is the name that appears in order forms, invoices, and client-area product lists.
3. In Module, select Blackwall.
4. Toggle the Create as Hidden switch to ON if you do not want customers to see the product in the public order form yet. This is recommended while you are configuring or testing the product.
5. Ensure that the Auto Assign to Products toggle switch is set to OFF.
6. Click Continue.
On the page that displays, ensure that the success message appears for your addon creation.
Click the Module Settings tab. It is on this tab that you select the Blackwall components and features that you wish to make available to your customers. The end user can then access and configure only the Blackwall features made available through their assigned package.
From the Server Group dropdown menu, select the new server group that you created earlier.
In the Website Settings panel, select the checkboxes for the default website settings that you want to include in your new product.
- Upstreams Use HTTPS - Check this checkbox if your origin(s) serve content over an HTTPS (port 443). When selected, GateKeeper will connect securely to the upstream rather than using HTTP. If left unchecked, GateKeeper will use HTTP (port 80) by default to fetch content from the origin.
- Enable HTTP/3 - GateKeeper speaks HTTP/3 (QUIC/UDP) to compatible clients, improving performance on modern browsers and mobile devices. Leave unchecked if you need to disable HTTP/3 for compatibility or DDoS concerns.
- Force HTTPS - Enable to automatically redirect all incoming HTTP (port 80) requests to HTTPS (port 443). When enabled, GateKeeper also adds security headers and rewrites http:// references in response bodies to https://. The recommended long-term solution is to configure the application to generate HTTPS URLs directly.
  Disable response-body rewriting while retaining Force HTTPS
  
  If you need to keep HTTP-to-HTTPS redirection enabled but prevent GateKeeper from rewriting http:// URLs in response bodies:
  1. Back up the domain configuration:
    cp -a /opt/nginx/etc/nginx/sites-enabled/<domain> /opt/nginx/etc/nginx/sites-enabled/<domain>.bak
  2. Find each occurrence of:
    sub_filter 'http://' 'https://';
  3. For each occurrence found, comment it out:
    # sub_filter 'http://' 'https://';
  4. Do not modify:
    proxy_redirect http:// https://;
    Leave Force HTTPS enabled.
  5. Reload the NGINX configuration or restart the service.
  Warning
  
  HTTP URLs generated by the application may cause mixed-content warnings if they are used to load browser resources.
  
  Updating the application to generate HTTPS URLs directly is the recommended long-term solution.
- Force Subdomain Redirect - Select one of these radio buttons to control how requests to any listed subdomains redirect back to the canonical hostname.
- Early Hints - Allows GateKeeper to send HTTP 103 “Early Hints” responses during the initial TLS handshake, so that browsers can start preloading resources (e.g., CSS/JS) before the final HTML is delivered. This improves load times, leading to a faster browsing experience.
Various component options are displayed in the next panel of the Module settings page. Select the checkboxes for the components that you want to make available to users of your new product.
1. For the section Monitoring & Analytics, Traffic Analytics (A1) is included as a mandatory monitoring component and cannot be edited/cleared.
2. For Bot Mitigation (S1) in the Security section:
  1. Place a check in the Bot Mitigation (S1) checkbox, if you wish to include this component.
  2. Once selected in the previous step, options for eight core rules display within the Function Configuration panel. Locate the rule that you wish to modify.
    Description of Blackwall core rules
    
    We recommend that you grant access to the following:
    - Search Engines - Search engine crawlers such as Google, Bing, Yahoo, and other indexing services that scan websites to discover and rank content in search results. These bots are generally considered trusted traffic and are important for SEO visibility, search discoverability, and content indexing. Administrators can choose to allow or deny access depending on business or security requirements.
    - Social Networks - Bots and crawlers operated by social media platforms such as Facebook, X (Twitter), LinkedIn, and others. These services typically access websites to generate link previews, retrieve metadata, or analyse shared content. Allowing these visitors helps ensure correct rendering of shared links and social media integrations.
    - Cloud Services - Automated traffic originating from recognised cloud-based services, infrastructure providers, or monitoring platforms. This category may include uptime monitoring tools, performance scanners, analytics platforms, and other legitimate cloud-hosted services. Depending on your environment, these services may be required for monitoring, integrations, or operational visibility.
    - Humans - Typical human visitors accessing the website through desktop browsers, mobile devices, or office networks. This category represents normal end-user traffic and is generally expected to have unrestricted access to website resources. Additional protections, such as content encryption, can be applied to secure content delivery and reduce automated analysis of sensitive page content.
    We recommend that you deny access for the remaining rules:
    - Content Scrapers - Automation tools designed to collect, copy, analyse, or archive website content at scale. These visitors are commonly associated with data scraping, competitive intelligence gathering, AI dataset collection, or automated content harvesting. Depending on business requirements, administrators may choose to block these visitors, challenge them with CAPTCHA, or apply content encryption to help protect sensitive or proprietary content.
    - Bots Emulating Humans - Advanced automation frameworks and next-generation bots that attempt to mimic legitimate browser behaviour in order to bypass traditional bot detection mechanisms. These visitors may simulate mouse movement, browser execution, session handling, or other human-like interactions. Because these bots are often associated with credential abuse, scraping, or automated attacks, they typically require stricter mitigation measures such as CAPTCHA enforcement, encryption, or access denial.
    - Suspicious Behaviour - Visitors exhibiting unusual, abnormal, or potentially abusive behaviour patterns detected by Blackwall’s analysis engine. This category may include excessive request rates, behavioural anomalies, suspicious navigation patterns, or activity commonly associated with automated abuse or account compromise attempts. Administrators can apply additional protections such as CAPTCHA challenges, encryption, or outright blocking to reduce the risk posed by suspicious traffic.
3. Optionally, place a check in the Web Application Firewall (S3) checkbox in the Security section. Then use the dropdown field in the Function Configuration section to select whether you want to grant or deny associated Security Violators.
4. Optionally, place a check in the L7 DDoS Protection (S2) checkbox in the Security section. Then use the field selector in the Function Configuration section to select one of the following.
  - DDOS Protection - Enables basic Layer 7 DDoS mitigation for the protected domain by limiting the number of simultaneous connections and the rate of requests from a single IP to help prevent volumetric or application-layer DDoS floods.
  - DDOS Protection Advanced - Enables additional Layer 7 DDoS protection for more advanced application-layer attacks. If enabled, GateKeeper will block attacking IPs at the firewall level for the entire cluster—returning a TCP RST or UDP rejection instead of serving HTTP 403 pages. Use this only if your site has experienced large-scale DDoS events.
5. Optionally, place a check in the Custom Rules (S4) checkbox in the Security section.
  
  Custom Rules are different to Blackwall's Core Rules. Whilst our default Core Rules greatly decrease bot traffic for your website(s), some visitor behavior might still present a cause for concern. This is where our Custom Rules engine can help you to eliminate those visitors from accessing your website. The Custom Rules engine may be used for bespoke purposes, but the main two purposes are:
  - Whitelisting (unblocking) of currently blocked services and clients.
  - Blocking of services and clients that currently have access to your site.
6. In the Performance section, optionally select Content Caching (P1) when the package should include Blackwall content-caching capabilities. Then from the available features in the Function Configuration section, optionally choose one or both:
  - Enable static resources caching - If checked, GateKeeper caches images, CSS, JavaScript, and other static files locally on the edge. This speeds up asset delivery and reduces load on your origin server.
  - Enable dynamic resources caching - If checked, GateKeeper also caches HTML pages and other 'dynamic' content for a configurable short period. Use with caution: caching dynamic content may cause delays in showing newly published data (e.g., blog posts, user-specific pages).
7. Optionally, in the CMS section, place a check in the checkbox that corresponds to any ruleset that you wish to enable.
Click Save Changes again.
Ensure that The changes to the addon have been saved banner displays.

Associate Blackwall Addon with Created Product

Log in to your WHMCS account as an administrator, using your login credentials.
Once your account homepage loads, from the top-right corner of the WHMCS admin panel, click wrench icon and then System Settings.
Click the Product Addons widget.
On the page displayed, scroll the Product Addons list to find the addon created in the previous section.
Click the Edit button that corresponds with the Product Addon you want to edit.
On the Product Addons - Edit Addon page that displays, click the Applicable Products tab.
In the Available Products panel, double-click the product you want to add to move it to the Selected Products panel. In this case, select the Product that you created earlier on this page.
Click Save Changes

Accepting a customer order

Following a customer ordering your new product, as the hosting provider, you must login to the WHMCS Admin Area and accept the order. Perform the following steps:

Log in to your WHMCS account as an administrator, using your login credentials.
From the navbar menu, click Orders and from the dropdown options available, select Pending Orders.
From the list of Pending Orders displayed, click the relevant Order ID to open the order details.
Carefully review the order information.
If the product or service needs to be provisioned when you accept the order, place a check in the Run Module Create checkbox. For example, this can create the customer's hosting account or trigger provisioning through the configured module.
Click Accept Order. This changes the order status from Pending to Active. If Run Module Create was selected in the previous step, WHMCS also runs the module's Create command for the associated service.

End user guide for plugin

After the WHMCS integration is configured, to use the product, you can use your cPanel or Plesk account directly, referring to the relevant guide below:

Alternatively, you can use the WHMCS Client Area, to use your WHMCS: cPanel or WHMCS: Plesk product. Refer to the following documentation:

After successfull purchase of the Blackwall Addon, you will see a new Blackwall Protection section appear under your Plesk and/or cPanel products in the WHMCS Client Area. All features and actions are exactly the same as the standard Blackwall Module product, which is documented in the WHMCS user guide. The landing page for your product in the Client Area is slightly different than in this user guide, but all other features and actions are identical.

Feedback