jrwebdeveloper1/meta-lead-ingester

Purpose and Integration Surface

A standalone Laravel package that receives real-time Meta Lead Ads and Google Ads Lead Form webhooks, verifies them, queues ingestion, and persists normalized provider-specific lead records. The package is integrated through Composer, its service provider, published configuration/migrations, and package-owned API/web routes.

Key paths: src/MetaLeadIngesterServiceProvider.php, config/meta-lead-ingester.php, routes/api.php.

HTTP Entry Points

Webhook endpoints are registered through the package API routes. Meta uses a webhook controller for verification/event intake; Google uses a dedicated controller. A separate web dashboard route/controller exposes stored lead/account information through Blade views.

Key paths: routes/api.php, src/Http/Controllers/WebhookController.php, src/Http/Controllers/GoogleWebhookController.php, routes/web.php, src/Http/Controllers/Web/DashboardController.php.

Provider Authentication Boundary

Incoming requests are authenticated before ingestion. Meta requests pass through HMAC-signature validation using the configured app secret. Google requests use a provider/account key mechanism, with account records serving as the trusted configuration boundary. Invalid or unauthenticated webhooks should not reach asynchronous processing.

Key paths: src/Http/Middleware/VerifyMetaSignature.php, src/Http/Middleware/VerifyGoogleSignature.php, src/Models/MetaAccount.php, src/Models/GoogleAccount.php.

Asynchronous Ingestion Pipeline

Controllers accept verified webhook payloads and dispatch provider-specific Laravel queue jobs. This decouples webhook response latency from lead retrieval/persistence and allows the configured queue connection/name to govern execution. Meta processing fetches lead details after receiving an event reference; Google processing saves its submitted lead-form payload through its own job path.

Key paths: src/Jobs/ProcessMetaLeadJob.php, src/Jobs/ProcessGoogleLeadJob.php, config/meta-lead-ingester.php.

Persistence Model

The package maintains separate account and lead tables/models for each provider rather than forcing a shared schema. Account records hold provider-specific credentials or identifiers; lead records preserve ingested lead data and provider association. Database migrations are publishable and run in the host Laravel application.

Key paths: database/migrations/2026_01_01_000000_create_meta_accounts_table.php, database/migrations/2026_01_01_000001_create_meta_leads_table.php, database/migrations/2026_01_01_000002_create_google_accounts_table.php, database/migrations/2026_01_01_000003_create_google_leads_table.php.

Meta External-Service Flow

Meta sends a webhook event to the package endpoint. After HMAC validation, the Meta job uses Meta/Graph API configuration—including API version and app secret—to obtain lead details, then writes a MetaLead associated with a MetaAccount. This is the principal outbound external-service boundary.

Key paths: src/Http/Controllers/WebhookController.php, src/Jobs/ProcessMetaLeadJob.php, src/Models/MetaLead.php, src/Models/MetaAccount.php.

Runtime and Presentation

The package runs inside a host Laravel application, requiring Laravel routing, middleware, Eloquent/database migrations, and a queue worker for reliable background processing. Its optional server-rendered dashboard is a conventional Blade presentation layer over the persisted ingestion data, not the lead-ingestion path itself.

Key paths: resources/views/dashboard.blade.php, resources/views/layout.blade.php, src/Http/Controllers/Web/DashboardController.php.