Installation

This page installs both halves of Perfex CRM Integration for WHMCS. Follow it in order. The whole process is done from two browser tabs plus your hosting panel's File Manager. No SSH and no command line are needed.

You should have upload.zip unpacked, giving you two files:

File	Goes into
🧩 perfex-module/module.zip	Perfex CRM
⚙️ whmcs-addon/addon.zip	WHMCS

Quick install (the short version)

For an experienced hosting admin, the whole job is five moves. Do them in this order.

1. 🧩 Perfex first. In Perfex CRM, go to Setup > Modules > Upload Module, upload module.zip, then Activate. Installing the Perfex side first means the receiving endpoint exists before WHMCS ever sends anything.
2. ⚙️ WHMCS addon. Upload and extract addon.zip into modules/addons/ so you end up with modules/addons/perfexbridge/perfexbridge.php, then activate Perfex CRM Bridge under System Settings > Addon Modules.
3. 🔓 Tick Access Control. On the addon's Configure screen, tick Full Administrator (plus any other role that should use it) and click Save Changes. Without this the module is invisible - it never appears in the Addons menu at all.
4. 🔗 Pair the two sides. Open Addons > Perfex CRM Bridge, paste the Connection code copied from Perfex into the Quick setup box, and click Connect. Details in Configuration.
5. ✅ Verify. Create a test client in WHMCS, click Run Sync Now, and confirm it appears in Perfex under Customers.

Every click, every checklist row and the full end-to-end verification are in the Detailed walkthrough below.

Detailed walkthrough

Order matters

Install the Perfex companion first. It creates the receiving endpoint. If you install the WHMCS addon first and start syncing, every event fails until the Perfex side exists, and you will spend time reading error logs about a problem you have not caused yet.

Step 1: Install the Perfex CRM companion

The Perfex companion is free, carries no licence key, and installs entirely from the Perfex admin area.

1. Log in to Perfex CRM as an Administrator.
2. Go to Setup > Modules.
3. Click the Upload Module button.
4. Choose module.zip in the file picker and upload it.
5. Perfex lists the module as WHMCS Bridge. Click Install if prompted, then click Activate.

If the upload is rejected for size

The Upload Module button posts the zip through PHP, so your server's upload_max_filesize and post_max_size limits must both be larger than the file. If the upload fails, either raise those limits in your PHP configuration, or use the manual fallback below.

Manual fallback: extract module.zip on your computer and upload the resulting whmcs_bridge folder into your Perfex installation's modules/ directory over FTP or your hosting panel's File Manager. The result must be modules/whmcs_bridge/whmcs_bridge.php. Then return to Setup > Modules and click Activate.

Confirm the Perfex side installed correctly

• A new WHMCS Bridge entry appears under the Perfex Setup menu. That page is where you will generate the shared secret in the next chapter.

Step 2: Install the WHMCS addon

WHMCS has no in-admin module installer. You place the files on disk yourself, then activate from the admin area. Your hosting panel's File Manager does everything.

1. Open your hosting panel's File Manager and navigate to your WHMCS installation's modules/addons/ directory.
2. Upload addon.zip into modules/addons/.
3. Use the File Manager's Extract action on the uploaded file, extracting into the same modules/addons/ directory.
4. Confirm the result is modules/addons/perfexbridge/perfexbridge.php. If you ended up with modules/addons/perfexbridge/perfexbridge/perfexbridge.php, the extract nested one level too deep. Move the inner folder up and delete the empty wrapper.
5. Delete the uploaded addon.zip from the server once extraction succeeded.

FTP alternative

Extract addon.zip on your own computer first, then upload the resulting perfexbridge folder into modules/addons/ over FTP. The end state is identical.

Now activate it:

6. In WHMCS, go to System Settings > Addon Modules.
7. Find Perfex CRM Bridge in the list and click Activate.

Step 3: Tick Access Control, or the module stays invisible

This is the most common "it did not install" report

After activating, WHMCS shows the module's configuration panel with an Access Control section listing your admin roles. You must tick at least Full Administrator, plus any other role that should use the module, and click Save Changes.

Until a role is ticked, the module does not appear in the left-hand Addons menu at all. The module is installed, its tables exist and its settings page works perfectly, but there is no link to it anywhere in the admin area. Nine times out of ten, "the module did not install" means this box was never ticked.

Concretely:

1. Still on System Settings > Addon Modules, click Configure next to Perfex CRM Bridge. WHMCS usually opens this panel automatically right after activation.
2. Under Access Control, tick Full Administrator. Tick any other admin role that should be able to open and configure the bridge.
3. Click Save Changes.
4. Refresh the admin area. Perfex CRM Bridge now appears under the Addons menu.

Access Control is the only thing on the Configure screen

Every real setting for this module lives on the module's own page at Addons > Perfex CRM Bridge, not on the WHMCS Configure screen. The Configure screen keeps only Access Control, because that is rendered by WHMCS core and cannot be moved. If you open Configure looking for the Perfex URL or the licence key, you are on the wrong screen. See Configuration.

Step 4: Open the module page

Go to Addons > Perfex CRM Bridge.

The page opens with the Setup checklist. On a fresh install it looks like this:

Checklist row	Expected state right now
Module tables present	🟢 tick
Connection configured	🔴 cross, nothing paired yet
Connection verified	⚪ dash, never checked
Sync enabled	🔴 cross until you tick Enable Sync
Cron delivering	🔴 cross, no cron activity logged yet
License / plan	⚪ dash, Free plan

That is the correct state for a freshly installed, unconfigured bridge. Every row is explained in Configuration.

Next, pair the two sides: Configuration.

Step 5: Verify the first sync end to end

Do this once, immediately after pairing, before you trust the bridge with real data. It takes two minutes and proves the entire pipeline.

1. Complete the pairing described in Configuration. The checklist rows Connection configured and Connection verified must both be green.
2. On the same page, under Settings > Sync behaviour, make sure Enable Sync is ticked, then click Save Settings. The Sync enabled row turns green.
3. In WHMCS, create a test client. Any name and email will do, for example a company named Bridge Test Ltd.
4. Return to Addons > Perfex CRM Bridge. The Queue pending counter near the top should read at least 1.
5. Click Run Sync Now. This forces an immediate delivery attempt without waiting for the cron. The page reports how many events were sent, failed and dead-lettered.
6. In Perfex CRM, open Customers. The test client is now there as a customer, with the WHMCS client's name and email as the primary contact.
7. Confirm both logs recorded it:
   • WHMCS side: the Recent activity table further down the module page shows a client.upsert row with status ok.
   • Perfex side: Setup > WHMCS Bridge, panel Recent inbound events, shows a matching client.upsert row with a green ok badge.
8. Delete the test client from both systems if you do not want to keep it.

"Run Sync Now" does not prove your cron works

Run Sync Now proves delivery. It does not turn the Cron delivering checklist row green, because that row deliberately tracks real WHMCS system cron activity. If that row is still red or amber an hour later, your WHMCS system cron is not running and nothing will sync automatically. Fix the cron before going live. See Troubleshooting.

Updating to a newer version

Both modules carry the same version and should always be updated together.

Perfex side. Upload the new module.zip through Setup > Modules > Upload Module, overwriting the existing module, then load any admin page. The companion detects the stale database version and applies its own migrations in place. If you prefer, deactivate and reactivate the module instead. Both routes are safe: every migration statement is guarded, so re-running it changes nothing that is already correct.

WHMCS side. Upload and extract the new addon.zip over modules/addons/perfexbridge/. WHMCS runs the module's upgrade routine when it sees the new version number. If in doubt, deactivate and reactivate the addon under System Settings > Addon Modules.

Your settings survive an upgrade

Settings, the shared secret, the licence key, the entity map and the logs all live in database tables that upgrades never drop. Deactivating the WHMCS addon does not delete its data either.

Uninstalling

1. WHMCS: System Settings > Addon Modules > Perfex CRM Bridge > Deactivate, then delete modules/addons/perfexbridge/ from disk.
2. Perfex: Setup > Modules, deactivate WHMCS Bridge, then remove the module.
3. If you want the data gone as well, drop the module's database tables in each system (take a backup first).
4. If a Pro licence was active, remove the key before uninstalling so the activation slot is released and the licence can be reused elsewhere. See Licensing and Pro activation.