Meta won't connect#

Connecting a Facebook Page to the CRM fails, or a previously working connection has gone unhealthy — tokens expire, pages change hands, app permissions drift. Every one of those states has a specific symptom. Read "What you see", match it, then work down.

Who this is for: workspace admins connecting Meta, and super admins who own the platform's Meta app settings.

Problem#

The OAuth flow errors out, the connection lands but shows unhealthy, or Meta settings show a failing health check. Leads will not flow until this is fixed — but this page is about the connection; the deeper "lead didn't arrive" path is on Leads not entering the CRM.

What you see#

Likely causes#

• Expired or revoked user token — the OAuth session timed out mid-flow, or the Facebook user's authorisation was removed.
• No Page selected — the account authorised but no Page was chosen, so no page token was stored.
• Missing app permissions — leads_retrieval, pages_show_list, pages_read_engagement, pages_manage_ads are required.
• App configuration drift — wrong/blank Meta App Secret, wrong OAuth callback URL, domain mismatch, or the Meta app in the wrong mode (development vs production).
• Webhook wiring — the app-side callback must be reachable at the CRM's webhook URL; the platform reports this as a health check.

Quick fix#

1. Reconnect: Admin → Lead Source Connections → the connection → Connect with OAuth again, and then use Select Page to store the page token. This fixes most token/selection issues in under two minutes.
2. Super admin: run Test Connection on Meta Developer Settings — it makes a real app-token call with the stored credentials.

Step-by-step fix#

1. Confirm the failure point. Health report status tells you which stage is broken: expiring is a warning (fix now, while it works); expired, invalid, missing, error need reconnecting. The connection label plus the missing-page-token error tells you it is specifically the page authorisation.
2. Re-run OAuth cleanly. Start from /admin/lead-source-connections, sign in to the right Facebook account (the one that administers the Page), grant all requested permissions, and finish. If you are bounced with an expired-session message, just start again — it means the flow sat open too long.
3. Select the Page. After OAuth succeeds, run Select Page and choose the exact Page whose leads you want. No page token = no lead reads; this is the single most common missed step.
4. Test the connection (super admin): Meta Developer Settings → Test Connection. If it fails, work the health checks on the same page top to bottom:
   • App Configuration — App ID and secret present and correct (the secret is encrypted and never displayed again; if in doubt, paste a fresh one).
   • OAuth Callback — must match the callback route for source meta.
   • Domain — matches what the Meta app declares.
   • API Connectivity — the platform can reach Graph.
   • Webhook — the inbound webhook route is registered and the app expects it.
   • Permissions — the four permissions listed above are granted.
5. Webhook sanity. The CRM's inbound endpoint is POST|GET /webhook/{tenant}/meta/{token}; a GET with the right verify token answers Meta's challenge immediately. If Meta's dashboard shows webhook verification failing, check the token in the connection record matches what you give Meta. Note: an unknown token produces a silent 200 and a log line (Webhook: unknown token) — verification can look "fine" to Meta while the CRM quietly rejects everything. Watch Admin → Webhook Logs during a test.
6. Environment check. On the Meta app side, confirm development vs production mode and that the CRM's environment setting (Meta Developer Settings → Environment) matches how the app is configured.

Admin fix#

• Reconnect + Select Page (above) fixes token, selection and most permission issues.
• After reconnecting, send a test lead (Meta's Lead Center test tool or a real ad) and confirm it lands — do not declare victory on the OAuth success screen alone.
• If the workspace uses the shared platform app, you cannot change app configuration — pass the failing health check to the super admin with the exact check name.

Developer fix#

• The OAuth routes are GET /oauth/{source}/{connectionId}/redirect and GET /oauth/{source}/callback; the Meta callback is oauth.callback with source=meta. The expired-session flash is messages.oauth_session_expired.
• Lead reads use the connection's stored page token. X-Hub-Signature-256 (HMAC-SHA256 with the connection's app secret, falling back to the platform MetaSettings::appSecret()); an empty secret means verification is skipped — acceptable in dev, a gap in production.
• Graph API version defaults to v22.0 (override with META_GRAPH_VERSION).
• Health statuses come from MetaConnectionHealthService and drive both the health report and leadhub:meta-health (every 6 hours).
• Connection issues become MetaIssue records with the lifecycle open → acknowledged → resolved, surfaced on the Needs Attention pages in both Super Admin and Agency panels.

Logs to check#

• Admin → Webhook Logs (/admin/webhook-logs) — invalid_signature means the app secret no longer matches; rejected means the connection is inactive.
• storage/logs/laravel.log — [leadhub:meta-health] unhealthy Meta connections detected, OAuth callback errors, Webhook: unknown token.
• Meta Ads → Needs Attention — open CRITICAL issues are listed with their detail; resolve them after fixing, so the badge stays meaningful.

When to escalate#

• OAuth completes but reconnecting never stores a page token, for every Page.
• Health checks fail in ways the UI cannot explain (e.g. API Connectivity down broadly) — that is a platform/network issue for the super admin or hosting team.
• Meta's own app review/policy rejects your app (permissions get revoked at the Meta side) — the app owner must resolve that inside Meta's dashboard; no CRM change fixes it.

Related guides#

• Leads not entering the CRM
• Meta overview
• OAuth & permissions
• Connect Meta