Configuration

Everything on this page assumes both modules are installed and activated, and that you can reach Addons > Perfex CRM Bridge in WHMCS and Setup > WHMCS Bridge in Perfex CRM. If either is missing, go back to Installation. In WHMCS the usual cause is the Access Control tick.

How the two sides authenticate

Both endpoints authenticate every request with an HMAC-SHA256 signature derived from a shared secret.

In plain language: the sender signs the request body with the secret and stamps it with a timestamp. The receiver recomputes the signature with its own copy of the secret and rejects anything whose signature does not match, or whose timestamp is more than 300 seconds old. That timestamp window is what stops somebody replaying a captured request later.

The consequence: the secret must be byte-for-byte identical on both sides, or every single request fails with a 401. Each endpoint also refuses all traffic while its own secret is empty, so a half-configured bridge is closed rather than open.

Both sides trim leading and trailing whitespace before use, so a stray space or newline picked up in copy-paste will not break you. Everything in between must match exactly.

Treat the shared secret as a credential

The shared secret grants write access to Perfex customers and contacts, and with a Pro licence to invoices, payments, orders and tickets on both sides. Rotate it on both sides immediately if either database, or a backup of one, is ever exposed. Secrets are stored in plaintext in tbladdonmodules (WHMCS) and tbloptions (Perfex), which is standard practice in both ecosystems, so anyone with database access has the secret.

Pairing: the fast path (recommended)

You do not need to copy settings back and forth by hand. Perfex generates a single Connection code that carries both the Perfex URL and the shared secret, and WHMCS consumes it in one paste.

Step 1: Generate the secret in Perfex

1. In Perfex CRM, go to Setup > WHMCS Bridge.
2. Next to Shared Secret, click Generate. The field fills with a strong 64-character random secret and becomes visible so you can see what you are about to save. The eye button toggles visibility back.
3. Click Save.

Step 2: Copy the Connection code

The page reloads and now shows a read-only Connection code field. Its value is a single string beginning with PBC1..

Click Copy. The button flashes "Copied!" when the code is on your clipboard.

The Connection code is a password

The code is PBC1. followed by base64url-encoded JSON containing your Perfex URL and your shared secret. That is encoding, not encryption. Anyone who obtains the code can talk to your bridge endpoints. Do not paste it into a public ticket, a chat channel, a screenshot or a support request.

If no Connection code appears

The code only renders when two conditions are met: your Perfex installation is served over HTTPS, and the saved shared secret is at least 32 characters. Clicking Generate without clicking Save is the usual cause. The page tells you which condition failed:

• "not served over HTTPS" - pairing needs HTTPS. Use the manual setup instead, or fix the certificate.
• "shorter than 32 characters" - click Generate, then Save, and the code appears.

Step 3: Paste it into WHMCS

1. In WHMCS, open Addons > Perfex CRM Bridge.
2. Find the green Quick setup box near the top of the page.
3. Paste the code into the field.
4. Click Connect.

What Connect actually does

In one step, and in this order:

1. It decodes the code and validates it hard: the PBC1. prefix, strict base64url, a well-formed JSON object, a URL that starts with https:// and passes URL validation, and a secret of at least 32 characters.
2. It sends a signed ping to your Perfex installation using the decoded URL and secret, and waits for the pong.
3. Only if that ping succeeds does it save the Perfex CRM URL and Shared Secret on the WHMCS side.
4. On the first pairing only, the ping also carries your WHMCS base URL, so the WHMCS URL field on the Perfex side is filled in for you. This happens only when your WHMCS is served over HTTPS, and it never overwrites a value that is already set.
5. It records the successful check, so the Connection verified checklist row turns green on the same page load.

On success you get a green banner naming the Perfex URL it paired with. On failure you get a red banner explaining exactly what went wrong, and nothing is saved. A code that fails verification can never overwrite a configuration that currently works.

Re-pairing later

Once WHMCS is configured, the Quick setup box becomes a low-key Re-pair form. Paste a fresh code any time you rotate the secret or move Perfex to a new domain. The same rule applies: a code that fails verification changes nothing.

Rotate the secret, then re-pair, in that order

If you click Generate and Save on the Perfex side, every existing WHMCS request instantly starts failing with HTTP 401 until you paste the new code into WHMCS. Do the two steps back to back. An old code copied before the rotation will be rejected, and the banner will tell you Perfex answered 401.

Pairing: the manual fallback

The Connection code is convenience, not magic. Everything it does can be done by hand, and you will need this route if your Perfex installation is not on HTTPS yet, or if your workflow forbids pasting a combined credential.

1. Generate a strong random secret of at least 32 characters. Use the Generate button on the Perfex settings page, or your own tool, for example openssl rand -hex 32.
2. In Perfex, on Setup > WHMCS Bridge, paste it into Shared Secret and click Save.
3. In WHMCS, open Addons > Perfex CRM Bridge, scroll to Settings > Connection, and:
   • set Perfex CRM URL to your Perfex base URL, for example https://crm.example.com, over HTTPS and with no trailing path;
   • paste the same secret into Shared Secret.
4. Click Save Settings.
5. Click Test Connection at the top of the page. You want the green "Connection OK" banner.
6. For Pro two-way sync, also set WHMCS URL on the Perfex settings page. Pairing would have done this for you.

WHMCS settings, section by section

All settings live on the module's own page

Open Addons > Perfex CRM Bridge and scroll to Settings. Do not look on the WHMCS Configure screen under System Settings > Addon Modules; that screen keeps only Access Control, which is rendered by WHMCS core and cannot be moved.

Click Save Settings to apply. The form is all or nothing: an invalid entry, for example a non-HTTPS URL, rejects the whole submission and changes nothing.

The two secret boxes never show their stored value

Shared Secret and Pro License Key always render empty, so a stored credential is never sitting in the page source of every admin who can open the module. Leave a box blank to keep its current value. Type into it to replace that value. To remove a Pro key entirely, tick Remove the stored key.

Connection

Setting	What it does	Sensible default
Perfex CRM URL	The base URL of your Perfex installation, for example https://crm.example.com. Must be HTTPS: the bridge refuses to send over plain HTTP.	Set automatically by pairing
Shared Secret	The HMAC secret. Must match the secret configured in Perfex under Setup > WHMCS Bridge. Leave blank to keep the stored one.	Set automatically by pairing

Sync behaviour

Setting	What it does	Sensible default
Enable Sync	The master switch. Untick to pause all outbound delivery. Events keep queueing while paused, so nothing is lost; they deliver on the next tick after you re-enable.	On, once configured
Order Sync Target (Pro)	What a WHMCS order becomes in Perfex. lead creates one Perfex lead per order. note adds a note on the Perfex customer instead. off does not sync orders at all.	lead
Two-Way Conflict Policy (Pro)	Which side wins when both systems changed the same client or contact since the last sync. See below.	newest_wins

Conflict policy options, one line each:

• newest_wins (default) - compares the incoming Perfex event time against the last sync time, and the more recent edit wins.
• whmcs_wins - keeps the WHMCS data and discards the conflicting Perfex edit.
• perfex_wins - applies the Perfex edit over the WHMCS data.

The conflict policy only fires on a genuine conflict

It applies only when both sides changed the same record since the last successful sync. An ordinary edit on one side, with the other side untouched, always applies. You are not choosing which system "wins" in general, only how to break a tie.

A note on newest_wins and server clocks

"Newest" compares the sending server's timestamp against the receiving server's last-sync time, so the two hosts' clocks matter. Keep both servers on NTP. If clock skew between your WHMCS host and your Perfex host is outside your control, prefer whmcs_wins or perfex_wins, which are deterministic.

Tickets

Setting	What it does	Sensible default
Ticket Reply Admin (Pro)	The WHMCS admin username used when a Perfex staff reply is synced into a WHMCS ticket. Leave it empty to attribute the reply to the Perfex staff member's name instead, posted as a non-admin reply.	Empty

Pro licence

Setting	What it does	Sensible default
Pro License Key	Leave empty for the Free plan. Paste your Pro key here to unlock the Pro features. Keys begin with sk_. Saving a key that has changed verifies it live, immediately.	Empty (Free)
Remove the stored key	A tick box that appears only when a key is stored. Ticking it and saving reverts the install to Free and releases this site's activation slot, so the licence can be used elsewhere.	Unticked
Check licence now (button, top of page)	Forces an immediate re-check of the key already stored, ignoring the once-a-day throttle.	-
Upgrade to Pro / Buy a Pro licence (links)	Open the checkout. On a non-Pro install these appear next to the key box, on the licence checklist row, and in the Pro teaser boxes.	-

Full detail is in Licensing and Pro activation.

Pro settings are safe to configure on Free

Order Sync Target, Two-Way Conflict Policy and Ticket Reply Admin all save perfectly well on a Free install. They simply have no effect until a valid licence is active, and the page says so under each field. Configure them in advance if you like.

Perfex CRM settings, field by field

Open Setup > WHMCS Bridge in the Perfex admin area, then click Save.

Connection

Field	What it does	Default / fallback
Shared Secret	Must match the WHMCS Shared Secret. Use Generate for a strong one, then Save. The eye button reveals or hides it. The endpoint rejects all traffic while this is empty.	Empty, endpoint closed
Connection code	Read-only. Appears once the saved secret is 32 characters or longer and Perfex is on HTTPS. Copy it into the WHMCS Quick setup box.	Rendered automatically
WHMCS URL	The base URL of the WHMCS installation running the addon. Needed only for Perfex to WHMCS traffic, which is a Pro feature. Must start with https:// or it is not saved.	Filled automatically on first pairing, never overwritten once set

Ticket sync (Pro)

Field	What it does	Default / fallback
Department mapping (WHMCS to Perfex)	Maps each WHMCS ticket department to a Perfex department. Renders as one dropdown per WHMCS department when the directory can be fetched, or as a manual textarea otherwise.	Empty, everything unmapped
Default department for unmapped WHMCS tickets	The Perfex department used for any WHMCS ticket whose department is not in the map.	"Lowest department id (automatic)"
Staff author for synced WHMCS staff replies	The Perfex staff member credited as the author of WHMCS staff replies mirrored into Perfex.	"First active admin (automatic)"
Create a Perfex task per synced ticket	When ticked, each synced ticket gains a linked Perfex task so your staff can log time against it with native Perfex timesheets.	Off

How department mapping renders

The normal experience is dropdowns. When the settings page loads it fetches your WHMCS support-department directory over the signed bridge and renders one row per WHMCS department, with a dropdown of your Perfex departments. Pick a target for each row, or leave it on - not mapped -, and click Save.

That fetch needs a working connection and a Pro-licensed WHMCS, because the department directory sits behind the same licence gate as ticket sync. When it cannot run, the page falls back automatically to a manual textarea and tells you why:

What you see	What it means
Dropdowns, one per WHMCS department	Everything is working
Textarea, "Couldn't fetch WHMCS departments (needs Pro + working connection)"	The bridge is not configured yet, WHMCS is unreachable from the Perfex server, or the WHMCS install is on the Free plan
Textarea, "Connection OK, but WHMCS has no support departments yet"	The fetch worked. Create departments in WHMCS under Support > Support Departments, then reload this page

The fetch is capped at a few seconds, so an unreachable WHMCS slows the settings page slightly but never hangs it.

The manual format is one mapping per line, the WHMCS department ID on the left and the Perfex department ID on the right:

1=2
2=5
3=5

With dropdowns showing, the link Advanced: edit the mapping manually opens the same textarea. While that manual editor is open, its text is what gets saved, overriding the dropdown selections.

Resolution order for an incoming ticket's department:

1. An exact match in the map.
2. Otherwise, the configured Default department.
3. Otherwise, the lowest Perfex department ID, chosen automatically.

A typo on a mapping line degrades gracefully to the fallback. It does not break saving, and it does not break syncing.

Time logged on the per-ticket task stays in Perfex

The optional Perfex task exists so your staff can use native Perfex timesheets against a ticket. Those time entries are not synced back to WHMCS, and the task is not closed automatically when the ticket closes.

Panels on the same page

The right-hand column of Setup > WHMCS Bridge carries three read-only panels:

• WHMCS plan - what plan the WHMCS side last reported (Pro, Free or Unknown), when the licence was last checked, and an Upgrade to Pro button when there is something to buy.
• Outbound queue - Perfex-side changes waiting to be pushed to WHMCS, with pending and dead counts, retry counts, next attempt time and the last error per row.
• Recent inbound events - what WHMCS has sent to this Perfex installation, with status and message.

These are your Perfex-side diagnostics. See How it works and daily use.

The setup checklist, row by row

The WHMCS module page opens with a six-row Setup checklist. Each row carries a green tick, an amber warning, a red cross or a grey dash, plus a one-line hint. Green across the board, with grey on the licence row if you are on Free, means the bridge is healthy.

Row	Green means	Anything else means
Module tables present	The outbox, map and log tables all exist.	🔴 a table is missing. Deactivate and reactivate the module under System Settings > Addon Modules to recreate it.
Connection configured	The Perfex URL and shared secret are both set.	🔴 not set yet. Paste a Connection code into Quick setup, or fill both fields under Settings > Connection.
Connection verified	A signed ping got a pong back, and the row shows how long ago.	🔴 the last check failed, and the row shows the error. Fix it, then click Test Connection. ⚪ never checked, or the last check is more than 24 hours old. Click Test Connection to refresh it.
Sync enabled	Outbound delivery is on.	🔴 sync is paused. Events keep queueing but are not delivered. Tick Enable Sync under Settings > Sync behaviour and save.
Cron delivering	The WHMCS system cron did real bridge work recently, and the row shows how recently.	🟠 no cron activity for a while. Check that the WHMCS system cron is running. 🔴 no cron activity has ever been logged. On a brand-new install that is normal until the first delivery; if it persists, your cron is not running.
License / plan	Pro is active.	⚪ no licence key, which is the Free plan and a perfectly supported way to run this module. 🔴 a key is set but does not validate. Check the key, then click Check licence now.

The "Cron delivering" row is deliberately hard to fake

Only a genuine WHMCS system cron tick turns this row green. Run Sync Now delivers your queued events, and proves delivery works, but it does not touch this row. That is the point: the row answers "will this keep working when nobody is watching?", and a button press cannot answer that question.

The row tracks actual bridge work: queue drains, log pruning and reconciliation passes. A long-idle but perfectly healthy install can therefore sit amber with nothing to fix, simply because there has been nothing to do.

Both Connect (pairing) and Test Connection refresh the Connection verified row.

Where to go next

• Verify the pipeline end to end: Installation, step 5.
• Unlock two-way sync, invoices and tickets: Licensing and Pro activation.
• Understand what syncs, and where the logs live: How it works and daily use.