Leads — Production Guide

Licensing

• Catalog slug: leads
• Default-included, non-billable for new workspaces
• Deactivate via Central module subscription tools to revoke access without dropping data

Bootstrap

On workspace provision:

1. Default modules installed (includes Leads)
2. LeadService::ensureDefaultStages() / LeadStageSeeder seeds New → … → Won / Lost
3. LeadService::ensureDefaultTags() / LeadTagSeeder seeds disposition tags on first Leads/tags API call

Existing workspaces without stages or tags get them lazily on first Leads API call.

Permissions rollout

New Leads permissions for existing workspaces must ship as an additive data migration using TenantPermissionSynchronizer::grantMissingDefaultRolePermissions([...]) (same pattern as Communication Templates). Do not re-seed roles or rely on login/dashboard to repair RBAC.

Status migration maps legacy open → active and won/lost → closed. Column rename: estimated_value → lead_value.

Include leads.manage_integrations in the grant list for lead ingest integrations.

Queue workers

Lead imports run on the dedicated imports queue. Meta Lead Ads ingest uses lead-ingest:

php artisan queue:work --queue=lead-ingest,imports,emails,default --sleep=1 --tries=3 --max-time=3600

Ensure at least one worker listens to imports and lead-ingest. Uploads use the configured filesystems.uploads disk (public locally / s3 in production) under imports/{tenant_uuid}/.

Lead ingest webhooks

Endpoint	Notes
POST /webhooks/leads/custom/{uuid}	Per-tenant Custom Webhook (HMAC or Bearer)
GET/POST /webhooks/leads/meta	Shared Meta Lead Ads ingress (signature + verify challenge)

CSRF-exempt under webhooks/leads/*. Configure Meta App ID/secret/verify token via Central PUT /api/central/v1/integrations/meta-lead-ads or META_LEAD_ADS_* env.

Step-by-step Meta Developer App creation, App Domains, permissions, OAuth vs webhook URLs, and tenant Connect Meta: Meta App Setup.

Meta production gates (required for customer Pages)

Before enabling Meta Lead Ads for customer workspaces:

1. Meta Business Verification completed for the platform app
2. Meta App Review approved for leads_retrieval + pages_manage_metadata (and related Page scopes)
3. App switched to Live Mode
4. Webhook subscription field leadgen pointed at https://{api}/webhooks/leads/meta with the configured verify token
5. OAuth redirect URI registered: https://{api}/api/oauth/leads/meta/callback
6. At least one worker consuming lead-ingest
7. Smoke: Connect Meta → select Pages → submit a Lead Ad form → lead appears in workspace

Without steps 1–3, only Meta test Apps / test users work.

Deploy checklist (ingest)

• [ ] Migrate ingest tables + leads.manage_integrations permission grant
• [ ] Queue worker includes lead-ingest
• [ ] META_LEAD_ADS_* (or Central settings) set for production
• [ ] Custom webhook HMAC/Bearer smoke
• [ ] Meta verify challenge + signed webhook smoke (sandbox)
• [ ] Confirm deactivated module:leads rejects ingress

Monitoring

• Platform audit events: lead_created, lead_updated, lead_deleted, lead_assigned, lead_stage_changed, lead_note_added, lead_follow_up_*, lead_import_completed, lead_import_failed, convert-related activity
• Mail + database notifications: assignment, follow-up created, follow-up due/overdue (crm:send-due-notifications every 5 minutes)
• Tenant mail settings with Central SMTP fallback

Scheduled jobs

Command	Cadence	Purpose
crm:send-due-notifications	Every 5 minutes (onOneServer)	Idempotent due/overdue follow-up (and task) notifications

Ensure the Laravel scheduler is running in production.

Deploy checklist

1. Migrate lead tables + Sprint 2 enhance migration + lead_assignment_histories + lead_imports + lead_tags / lead_lead_tag + lead_follow_ups.lead_tag_id
2. Deploy frontend (Kanban/table, KPIs, Manage tags, export, import wizard/history, convert → contact when Contacts installed, notifications)
3. Confirm module:leads + expanded permissions (including leads.import)
4. Confirm queue worker includes imports
5. Smoke: register/login → Leads board → Manage tags → create lead (default tag) → apply Follow Up Later with due date → DnD stage → export/import → convert (On Boarded contact when Contacts installed)

Related

• Meta App Setup — Meta Developer App + EloSync wiring
• Meta Lead Ads Integration
• Leads overview