Troubleshooting

Work through this page in order. The first three sections cover the overwhelming majority of support requests.

Before anything else, open Addons > Perfex CRM Bridge in WHMCS and read the Setup checklist. It is designed to point straight at the problem, and each row is explained in Configuration.

Quick reference

Symptom	Most likely cause	Fix
Module missing from the WHMCS Addons menu	No admin role ticked under Access Control	Tick Access Control
Every send fails immediately	The Perfex URL starts with http://	Use HTTPS
auth.rejected rows in the Perfex inbound log	The shared secret does not match	Re-pair
"Two-way sync requires Pro" on the Perfex outbound queue	The WHMCS side is on the Free plan	Activate Pro
Events queue but nothing is delivered	Sync is paused, or the WHMCS cron is not running	Check the cron
One invoice never lands and retries forever	The invoice currency does not exist in Perfex	Add the currency
The licence will not activate	Missing key, or no connectivity to the licensing service	Read the banner colour
No Connection code on the Perfex page	Perfex is not on HTTPS, or the saved secret is too short	Generate and Save
Department mapping shows a textarea, not dropdowns	Free plan, or WHMCS unreachable from Perfex	Mapping fallbacks
Rows stuck in dead state	15 failed attempts for the same reason	Replay dead rows

The module is not in the Addons menu

Symptom. You activated Perfex CRM Bridge under System Settings > Addon Modules, WHMCS said it activated, and the module is nowhere in the left-hand Addons menu.

Cause. No admin role has been granted access. WHMCS hides an addon module entirely from any role that is not ticked, so the module is installed and fully functional but has no link anywhere in the admin area. This is by far the most common "it did not install" report.

Fix.

1. Go to System Settings > Addon Modules.
2. Click Configure next to Perfex CRM Bridge.
3. Under Access Control, tick Full Administrator, plus any other role that should use the module.
4. Click Save Changes.
5. Refresh the admin area. The module now appears under Addons.

Nothing else lives on that Configure screen

Every real setting is on the module's own page at Addons > Perfex CRM Bridge. The Configure screen keeps only Access Control, because WHMCS core renders it and it cannot be moved.

Every send fails immediately, or the URL is rejected

Symptom. Events queue and fail instantly. The Recent activity log fills with connection errors. Or the Perfex CRM URL field refuses to save at all.

Cause. HTTPS is required by design. The HTTP transport is pinned to the https protocol and verifies the TLS certificate. A http:// URL fails every single send, and the Perfex-side WHMCS URL field likewise refuses to save unless it starts with https://.

Fix.

1. Set Perfex CRM URL to an https:// address on the WHMCS side.
2. Set WHMCS URL to an https:// address on the Perfex side.
3. Make sure both certificates actually validate from the other server, not just in your browser. A self-signed certificate works only if the calling server trusts it.
4. Click Test Connection on the WHMCS module page.

There is no setting to disable HTTPS verification

This is deliberate. Your shared secret and your customer data travel over this channel. If a certificate does not validate, fix the certificate.

auth.rejected rows in the Perfex log

Symptom. WHMCS reports HTTP 401 errors. In Perfex, Setup > WHMCS Bridge > Recent inbound events shows red auth.rejected rows.

Cause. The shared secret does not match on the two sides, or the request timestamp is outside the 300-second window. In practice it is nearly always the secret: someone regenerated it on one side and never re-paired the other.

Fix, the fast way.

1. In Perfex, Setup > WHMCS Bridge, copy the current Connection code.
2. In WHMCS, Addons > Perfex CRM Bridge, paste it into the Re-pair box and click Connect.
3. Click Test Connection. You want the green "Connection OK" banner.
4. Click Run Sync Now. The queued events that were failing now deliver.

Fix, by hand. Re-paste the exact same secret into both Shared Secret fields and save on both sides. Leading and trailing whitespace is trimmed automatically, but everything in between must match character for character.

If it is not the secret. Check both servers' clocks. A drift of more than 300 seconds between them causes every request to be rejected as a replay. Put both hosts on NTP.

Rejected rows are rate-limited

Perfex records at most 10 auth.rejected rows per minute, so a misconfigured sender cannot fill your disk. If you see exactly 10 in a minute, assume there were more.

"Two-way sync requires Pro" on the Perfex outbound queue

Symptom. You edit a customer in Perfex. The Outbound queue panel on Setup > WHMCS Bridge shows the row with the message "Two-way sync requires Pro on the WHMCS side." and an Upgrade to Pro link. Attempts climb, and eventually the row goes dead.

Cause. Two-way sync is a Pro feature, and the licence lives on the WHMCS side. Your WHMCS installation is on the Free plan, so its inbound endpoint answers 403 to any Perfex-originated change. The Perfex companion is behaving correctly by queueing and retrying.

Fix. Activate a Pro licence on the WHMCS side. See Licensing and Pro activation. Once Pro is active, WHMCS pushes the new plan state to Perfex immediately, the upgrade prompt disappears, and pending rows deliver on the next Perfex cron run.

Rows that already went dead while you were on Free will not retry by themselves. See Rows stuck in dead state.

Check the plan panel first

The WHMCS plan panel sits directly above the Outbound queue on the Perfex settings page, for exactly this reason. If it says Free, you have your answer without reading a single queue row.

Nothing syncs at all

Symptom. Events appear in the queue, Queue pending climbs, and nothing ever reaches Perfex. No errors, just silence.

There are two causes, and the checklist distinguishes them.

Cause A: sync is paused

The Sync enabled checklist row is red.

Fix. On the WHMCS module page, under Settings > Sync behaviour, tick Enable Sync and click Save Settings. Nothing was lost while you were paused; events kept queueing and will now drain.

Cause B: the WHMCS system cron is not running

The Cron delivering checklist row is red or amber.

Fix.

1. Prove the bridge itself works by clicking Run Sync Now. If your queue drains, delivery is fine and the problem is genuinely the cron.
2. Check WHMCS's own cron status under Utilities > System > System Health Status. WHMCS reports when the system cron last ran.
3. If the cron has not run recently, fix it at the server level. Your hosting panel's cron manager, or your server's crontab, is where the WHMCS cron command lives. WHMCS's own documentation gives the exact command for your version.
4. Once the cron runs again, the Cron delivering row turns green on the next page load after real bridge work happens.

Run Sync Now cannot turn the cron row green

That row deliberately tracks only genuine WHMCS system cron activity, because it answers "will this keep working when nobody is watching?". A button press cannot answer that question. If Run Sync Now works but the row stays red for hours, your cron is not running.

An amber cron row is not always a problem

The row tracks real bridge work: queue drains, log pruning and reconciliation. A healthy but idle installation with no changes to sync can sit amber with nothing to fix.

An invoice is stuck and never reaches Perfex

Symptom. One invoice fails repeatedly. The log message names a currency, and the row keeps retrying with a growing delay.

Cause. The invoice's currency is not configured in Perfex. Perfex rejects the invoice, correctly, because it cannot record a total in a currency it does not know.

Fix.

1. In Perfex, go to Setup > Finance > Currencies.
2. Add the currency, using the exact ISO code that WHMCS uses, for example EUR or USD.
3. Do nothing else. The queued event retries on its own schedule and succeeds on the next attempt.

You have about 40 hours

The retry schedule allows 15 attempts spanning roughly 40 hours. Add the currency inside that window, or the row dead-letters and has to be replayed manually. If you are about to backfill historical invoices, add every currency your clients use first.

The related case: "Not mapped (will retry)"

A child record arrived before its parent: a contact whose client is not yet in Perfex, an invoice whose client is not yet mapped, or a ticket reply whose ticket has not synced.

This normally heals itself. The queue delivers in order, the parent lands, and the child succeeds on its next attempt. It only becomes a real problem when the parent will never sync, for example when you backfilled services without backfilling clients. In that case, queue the parent (edit the client in WHMCS, or run a Clients backfill) and the children follow.

The licence will not activate

Symptom. You pasted a key and the install still shows Free.

Two things are needed for Pro: a valid key and connectivity from your WHMCS server to the licensing service. Read the banner colour, because it tells you which one is missing.

Banner	Meaning	Fix
🔴 Red	The licensing server actively rejected the key, and the message says why.	Re-copy the key from the purchase email in one go. Keys are 32 characters and may contain punctuation, so do not trim or reformat. If the message mentions installs or a quota, free an activation slot by removing the key from an installation that no longer needs it.
🟠 Amber	Your server could not reach the licensing service. This is not a rejection.	The key is saved and retries continue. Allow outbound HTTPS to api.freemius.com through any egress firewall or proxy on the WHMCS server. Then click Check licence now.
⚪ No banner at all	You saved the same key that was already stored, so nothing was re-checked.	Click Check licence now.
Header says "awaiting first verification"	A key is stored but has never been confirmed.	Click Check licence now.

Other checks:

• Make sure the key is in Pro License Key under Settings > Pro licence on the module's own page, not somewhere on the WHMCS Configure screen.
• Press Check licence now and wait a few seconds between presses. A rapid second press answers "checked a moment ago" without sending a request.
• If Pro is active in WHMCS but Perfex still shows Free, press Check licence now or Test Connection in WHMCS. Both deliver the plan state to Perfex immediately. Then reload the Perfex settings page.

Full detail is in Licensing and Pro activation.

No Connection code appears in Perfex

Symptom. You are on Setup > WHMCS Bridge, you saved a secret, and there is no Connection code field, just a grey note.

Causes and fixes. The note itself tells you which applies.

Note	Cause	Fix
"not served over HTTPS"	Pairing requires an HTTPS Perfex installation.	Fix the certificate, or use the manual setup.
"shorter than 32 characters"	The saved secret is too short. Clicking Generate without clicking Save is the usual cause.	Click Generate, then Save. The code appears on reload.

Pairing fails with "the shared secret does not match"

Symptom. You pasted a Connection code into WHMCS and got a red banner mentioning HTTP 401.

Cause. The code carries a secret that Perfex no longer has. Almost always this is a code copied before a later Generate and Save, or a Generate that was never saved.

Fix. In Perfex, click Save on the settings page so the current secret is genuinely stored, copy a fresh Connection code, and paste that. Nothing was stored on the WHMCS side by the failed attempt, so your previous working configuration is intact.

Department mapping shows a textarea instead of dropdowns

Symptom. The Perfex settings page shows a plain textarea for department mapping rather than one dropdown per WHMCS department.

Cause. The page could not fetch your WHMCS support-department directory. The hint under the textarea says which case applies:

Hint	Cause	Fix
"Couldn't fetch WHMCS departments (needs Pro + working connection)"	The bridge is not configured, WHMCS is unreachable from the Perfex server, or WHMCS is on the Free plan. The directory sits behind the same licence gate as ticket sync.	Complete pairing, check that Perfex can reach your WHMCS URL over HTTPS, and activate Pro.
"Connection OK, but WHMCS has no support departments yet"	The fetch worked; there is simply nothing to map.	Create departments in WHMCS under Support > Support Departments, then reload the Perfex page.

The manual whmcs_deptid=perfex_department_id textarea always works in the meantime, one mapping per line. Syncing is not blocked by this: an unmapped ticket falls back to your default department, or to the lowest Perfex department ID.

Rows stuck in dead state

Symptom. The Dead events counter on the WHMCS module page, or the dead count on the Perfex Outbound queue panel, is above zero.

Cause. Those rows failed 15 times over roughly 40 hours for the same reason. Dead rows are never retried automatically and never pruned, deliberately, so that you can inspect them.

Fix.

1. Find out why. Open Recent activity in WHMCS, or the Outbound queue's "Last error" column in Perfex, and read the error on the affected rows. The cause is nearly always one of: a missing Perfex currency, a secret mismatch, a Free plan blocking a Pro event, or Perfex having been offline.

2. Fix that root cause first. Replaying a row without fixing the cause simply burns another 40 hours.

3. Re-queue the work. The safest route needs no database access:

   • For clients, contacts, invoices, services and domains, re-trigger the event. Edit and save the record in WHMCS, or run the backfill wizard in mode Only new (not yet synced).
   • For Perfex-side changes, edit the Perfex record again to queue a fresh event.

4. If you prefer to replay the original row and you have database access, reset it to pending. Take a backup first:

   UPDATE mod_perfexbridge_outbox
      SET status = 'pending', attempts = 0, next_attempt_ts = 0
    WHERE id = 123;

   Replace 123 with the row ID you want to replay. The equivalent Perfex-side table is tblwhmcs_bridge_outbox, using your Perfex table prefix.

A change in Perfex never reaches WHMCS

Work down this list:

1. Is the WHMCS side Pro? Check the WHMCS plan panel on the Perfex settings page. Two-way sync is Pro only.
2. Is the WHMCS URL set on the Perfex side? Setup > WHMCS Bridge > WHMCS URL, HTTPS, no trailing path. Pairing normally fills this in on the first pair, but it never overwrites a value that was already there.
3. Can the Perfex server reach WHMCS over HTTPS? The Perfex push client pins HTTPS and verifies the certificate, exactly like the WHMCS side.
4. Is the Perfex cron running? Perfex-originated changes are delivered on the Perfex cron, not the WHMCS one. Check your Perfex cron job.
5. Is the record mapped? Only customers that were synced from WHMCS are mapped. A customer created directly in Perfex has no WHMCS counterpart and is never pushed. Likewise, tickets created directly in Perfex stay in Perfex.
6. Read the Outbound queue panel. It names the last error per row.

A change bounced back and overwrote my edit

Symptom. You edited a record in one system, and it reverted to the other system's value.

Cause. Both sides changed the same record since the last sync, and your Two-Way Conflict Policy decided the winner.

Fix. Choose the policy that matches how your team works, under Settings > Sync behaviour on the WHMCS module page:

• newest_wins (default) - the more recent edit wins. Requires both server clocks to be accurate.
• whmcs_wins - WHMCS is always authoritative.
• perfex_wins - Perfex is always authoritative.

If both hosts' clocks are outside your control, avoid newest_wins: clock skew shifts its decisions by the amount of the skew.

Customers receive two emails for one ticket reply

Symptom. A Perfex staff member replies to a synced ticket, and the customer gets two notifications.

Cause. Perfex sends its own ticket-reply email, and the reply synced into WHMCS makes WHMCS send its own notification too. This is documented behaviour, not a sync loop. Email suppression only covers the WHMCS to Perfex direction.

Fix. If your customers live in the WHMCS client portal, disable the Perfex ticket-reply email template under Setup > Email Templates > Tickets in Perfex.

Still stuck: what to collect before contacting support

Have these ready and the answer usually comes back on the first reply:

• The version of both modules, currently 1.3.4, and confirmation that both sides are on the same version.
• WHMCS version, Perfex CRM version, and the PHP version on both servers.
• A screenshot of the Setup checklist from the WHMCS module page.
• The Queue pending and Dead events counts.
• The relevant rows from Recent activity in WHMCS and Recent inbound events in Perfex, with the full message column.
• What you were doing when it failed, and whether it ever worked.

Never send your shared secret or Connection code

The Connection code contains your shared secret. Neither belongs in a support ticket, a screenshot or a chat message. Support never needs either one to diagnose a problem.