Troubleshooting

Running into issues? Don't worry - most problems have simple fixes! Find your issue below and follow the solution.

Webhook Verification Fails

Error: "The callback URL or verify token couldn't be validated."

Possible Causes & Fixes:

#	Cause	Fix
1	URL is not HTTPS	Install an SSL certificate on your server
2	Typo in callback URL	Copy-paste directly from the module settings
3	Typo in verify token	Copy-paste directly from the module settings
4	Server is blocking requests	Check your firewall / security plugins
5	.htaccess redirect issues	Make sure the URL doesn't redirect (no www ↔ non-www redirect issues)
6	Selected "User" instead of "Page"	Change the dropdown to "Page" in Facebook webhooks

How to Debug:

1. Open your browser and visit your webhook URL directly:

   https://yourcrm.com/facebookleadsintegration/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123

2. If working correctly, you should see test123 displayed on the page
3. If you see an error page, the issue is on your server side

tip

Still not working? Check your server's error logs at /path/to/your/crm/application/logs/

"Invalid Scopes" Error During Facebook Login

Error: "Invalid Scopes: pages_manage_metadata"

Fix:

This means the module is requesting a deprecated permission. Make sure you're using the latest version of the module (v2.0.0+), which uses the correct permissions:

• pages_show_list
• pages_read_engagement
• leads_retrieval
• pages_manage_ads
• ads_management

Update your module to the latest version to fix this.

"Error Accessing App" / "App Not Active"

Error: When trying to connect with Facebook, you see "Error Accessing App" or "The app is not active."

Possible Causes & Fixes:

#	Cause	Fix
1	Wrong App ID in module settings	Double-check the App ID matches your Meta App
2	App was deleted or disabled	Check your app at developers.facebook.com/apps
3	You're not an admin/developer of the app	Add yourself in App Roles → Roles
4	App restrictions	Check App Settings → Basic → App Restrictions

Test Lead Works but Real Leads Don't Arrive

The module's "Send Test Lead" button works, but real leads from Facebook don't appear.

Check These:

#	Check	How
1	Is your Page subscribed?	Settings → Connected Pages → Must show "Monitoring"
2	Is the webhook verified?	Settings → Connection Status → Webhook must be green
3	Is "leadgen" subscribed?	Meta App → Webhooks → Page → "leadgen" must be checked
4	Is the ad using the right Page?	Ads Manager → Ad Set → Make sure it uses the subscribed Page
5	Is the ad running?	Ads Manager → Campaign status should be "Active"

Test with Facebook's Tool:

Use the Lead Ads Testing Tool to send a real webhook test lead. If this works but actual ads don't, the issue is likely with your ad campaign setup.

500 Error on Module Pages

Symptom: Module pages show a blank page or "500 Internal Server Error"

Fixes:

1. Check PHP error logs:

   /path/to/your/crm/application/logs/log-YYYY-MM-DD.php

2. Common causes:

   • PHP version too old (need 7.4+)
   • Missing PHP extensions (cURL, JSON)
   • File permissions incorrect
   • Module files corrupted during upload

3. Fix file permissions:

   find /path/to/modules/facebookleadsintegration -type f -exec chmod 644 {} \;
   find /path/to/modules/facebookleadsintegration -type d -exec chmod 755 {} \;

4. Re-upload the module if files might be corrupted

Copy Button Not Working

Symptom: Clicking the "Copy" button next to webhook URL or verify token does nothing.

Fix:

• Make sure your CRM is accessed via HTTPS - clipboard API requires a secure context
• Try manually selecting the text and pressing Ctrl+C
• Check browser console for JavaScript errors (F12 → Console tab)

Leads Are Stuck in "Pending Retry"

Symptom: Sync History shows leads with "Pending" status that aren't being processed.

Fixes:

1. Process manually: Go to Sync History → Click "Process Retry Queue"
2. Check cron: The retry queue processes automatically via Perfex CRM's cron job
   • Make sure your cron job is running: Setup → Settings → Cron Job
   • The cron URL should be called every 5 minutes
3. Check the error message in Sync History for why the lead failed initially

Access Token Expired

Symptom: Connection test fails with "Token expired" or leads stop arriving.

Fix:

The module exchanges short-lived tokens for long-lived tokens (valid for ~60 days). To refresh:

1. Go to Meta Leads → Settings
2. Scroll to Connected Pages
3. Click "Connect with Facebook" again
4. Log in and grant permissions
5. The token is automatically refreshed

tip

Set a reminder to reconnect every 50 days to keep the token fresh!

Fields Not Mapping Correctly

Symptom: Lead data appears in the wrong fields or is missing.

Debug Steps:

1. Go to Sync History → Click on a lead entry to see the raw data
2. Check what field names Facebook is sending
3. Go to Field Mapping → Make sure the Facebook field name matches
4. Remember: Standard fields (email, full_name, phone_number) map automatically

Common Field Name Issues:

What You Expect	What Facebook Sends	Solution
name	full_name	Already auto-mapped
phone	phone_number	Already auto-mapped
company	company_name	Already auto-mapped
budget	custom_question_1	Create a custom mapping

Module Doesn't Appear After Installation

Fixes:

1. Check file location: Module folder must be at modules/facebookleadsintegration/
2. Check file name: Main file must be facebookleadsintegration.php (all lowercase)
3. Activate the module: Go to Setup → Modules → Click Activate
4. Check permissions: Files should be readable by the web server (644 for files, 755 for directories)

Server-Specific Issues

Cloudflare Users

If using Cloudflare, whitelist Facebook's webhook IPs:

1. Go to Cloudflare → WAF (Web Application Firewall)
2. Create a rule to Allow requests from Facebook
3. Or add these to your firewall whitelist:
   • Facebook's webhook IPs can be found at: https://developers.facebook.com/docs/sharing/webmasters/getting-started/webhooks/

Nginx Users

Make sure your Nginx config allows POST requests to the webhook URL and doesn't block Facebook's User-Agent.

Shared Hosting

Most shared hosting works fine. If you have issues:

• Check if allow_url_fopen is enabled in PHP
• Check if cURL extension is installed
• Check if your host blocks incoming webhooks (some security-focused hosts do)

Still Need Help?

If none of the above fixes your issue:

1. Check the Perfex CRM error logs
2. Check the module's Sync History for error messages
3. Take a screenshot of any error messages
4. Contact us at [email protected] with:
   • Your Perfex CRM version
   • PHP version
   • The error message
   • Steps to reproduce the issue

Check the FAQ for more answers FAQ