WHMCS Configuration

This integration works with HSPs, Resellers, and Marketplaces.

Blackwall provides an integration plugin for the WHMCS billing system. During installing the plugin, the 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 assigned to a customer account, the corresponding Blackwall components and features are made available to the customer. The end user can then access and configure only the Blackwall features made available through their assigned package.

Install the plugin

We recommend managing Blackwall via GateKeeper directly or one of Blackwall's integration modules, not both. Running them concurrently can cause configuration conflicts and complicate troubleshooting. Pick one interface and use it consistently for all changes. This matters especially in hosted environments, where service providers don't have access to customer integration module instances.

To install the Blackwall plugin on the WHMCS server:

Download the latest Blackwall WHMCS plugin archive:

curl -O https://repo.botguard.net/modules/blackwall-whmcs-latest.zip

or

wget https://repo.botguard.net/modules/blackwall-whmcs-latest.zip

Extract the contents of the archive to the path where WHMCS is installed, like:
```
unzip blackwall-whmcs-latest.zip -d /var/www/html/whmcs/
```

To install necessary hooks for Plesk and cPanel modules, use the following command:

cp -r /root/modules/servers/Blackwall /var/www/html/modules/servers/ && cp -r /root/includes/lib/* /var/www/html/includes/ && cp -r /root/includes/hooks/* /var/www/html/includes/

Set the required permissions for the extracted Blackwall module folder:
```
chown apache:apache -R /var/www/html/whmcs/modules/servers/blackwall
```

Note

WHMCS directory path and username may differ in various Linux distributions.

Configure the plugin

Before configuring the pluging, ensure that you have understood the following terminology overview:

Server = the GateKeeper API endpoint.
Server Group = the WHMCS group that points products to a GateKeeper instance.
Product Group = the storefront/order-form category that contains customer-facing products.
Product = the item customers order in WHMCS.

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

Add your Blackwall server.
Create a WHMCS Server Group and add your Blackwall server to it.
Create a WHMCS Product Group.
Create a WHMCS Product and assign the Server Group to the Product.

Each product can use a different Server Group, allowing you to connect different products to different GateKeeper instances.

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.

Create a WHMCS Product Group

Before creating a product, create a WHMCS Product Group to organise the product in the WHMCS order form.

1. 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 dropdown menu displayed, click System Settings.
From the widgets displayed, click Products/Services.
When the Products/Services page displays, click + Create a New Group.
Populate the Create Group page fields as follows:
1. In Product Group Name, enter a meaningful name for the group. For example: Blackwall
2. In the URL field, enter the friendly URL slug for the product group. For example: blackwall
3. Optionally, in the Product Group Headline, enter a heading that your customers see on the order form.
4. Optionally, in the Product Group Tagline, enter a short description for the product group.
5. Select the required Order Form Template.
6. Select the payment gateways that customers can use for products in this group.
7. Select the Hidden checkbox if you do not want this product group to appear on the public WHMCS order form. This is useful while you are configuring or testing the products in the group. Hidden product groups are not displayed to customers in the order form, but administrators can still manage them in WHMCS.
8. Click Save Changes.

Create a WHMCS Product

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

Log in to your WHMCS account as an administrator, using your login credentials.
Open the menu item Addons » Apps & Integration.
Start typing Blackwall in the search box.
Once autocomplete finds the Blackwall add-on module, click the Blackwall widget.
On the page displayed, click the Create New Product button.
On the Create a New Product page that displays, populate the following fields:
1. Select the Product Type that best matches how you want WHMCS to manage your new product. For the Blackwall plugin, Shared Hosting is typically used, unless your internal setup requires another type.
2. In Product Group, select the group that should contain the product. In this example, we previously created the Product Group Blackwall.
3. In Product Name, enter the customer-facing name of the product. This is the name that appears in WHMCS order forms, invoices, and client-area product lists.
4. Review the automatically generated URL, which is based on the selected product group and product name. Use this friendly URL to link to this product.
5. In Module, select the required provisioning module. If the product does not need automated provisioning during setup, leave this as No Module.
6. 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.
7. Click Continue.
On the page that displays, 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 the customer. 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.
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 Saved Successfully banner displays.

Each product can use a different Server Group. This allows you to connect different products to different GateKeeper instances, which in turn provides flexibility.

Feedback