How it works
What this system does
Connect website and form conversion evidence with existing HubSpot contacts, while reporting overall traffic from GA4. PostgreSQL holds raw events, queue state, attribution decisions, and complete traffic snapshots.
This package implements the attribution layer alongside the Intelligent Lead Routing & Response blueprint and the attribution phase of the Revenue Operations Intelligence blueprint.
The six-workflow lifecycle
- Capture: workflow 01 authenticates a trusted backend event and stores it before acknowledging receipt.
- Reconcile: workflow 02 matches an existing HubSpot contact, normalizes campaign evidence, preserves original source, proposes newer latest-touch updates, and audits decisions before CRM changes.
- Prepare properties: workflow 03 manually creates the required custom contact properties before processing begins.
- Sync traffic: workflow 04 refreshes the previous seven complete GA4 days, using the property timezone. A snapshot becomes visible only after all pages and the separate totals request succeed.
- Report: workflow 05 returns aggregate traffic, captured conversions, and quality information using a separate report credential.
- Operate: workflow 06 records automatic workflow failures and checks queue health every 15 minutes. Add your own notification channel if alerts are needed.
Source preservation and identity rules
Original source is preserved once present. Latest source changes only with reliable newer evidence. Manual locks and source conflicts hold automatic changes. Only custom revops_ contact properties are written; native HubSpot traffic-source fields and company source fields are untouched.
Use a stable event_id per producer and the same submission_id across events for one conversion. Direct contact ID/email or an unambiguous shared submission authorizes matching. Visitor/session hints alone do not. The worker looks up contacts; your normal form-to-CRM flow must create them.
What the report means
GA4 describes aggregate sessions, distinct users, engagement, page views, and configured key events. Captured conversions describe tracked submissions and matched contacts. These are separate views with different cohorts; this package does not claim person-level GA4 matching, revenue attribution, ROAS, or an inferred conversion rate. Multiple submissions can belong to one contact.
Validation status
The supplied validation report records 61 local checks. Live n8n execution, PostgreSQL functions and concurrency, Google OAuth and GA4 compatibility, HubSpot permissions, and actual website integration were not verified in that source report. All six workflows import inactive; HubSpot writes default to off. Importing the package into this library does not deploy it to those services.
How to use
Before you start
- A compatible n8n instance that supports the exported node versions.
- A dedicated PostgreSQL 14+ application database reachable from n8n over an encrypted connection.
- HubSpot contacts already created by your form-to-CRM flow, plus a private app credential with the required contact and setup permissions. Optional review tasks require the relevant task permissions.
- A GA4 property collecting your actual site traffic, Google Analytics Data API access, and Google OAuth with analytics.readonly scope.
- A trusted form backend, a consent layer, and GA4/GTM event integration if using the browser helper. No AI credential is required.
Import and configure
- Download the complete package, extract the ZIP, and read the full setup manual. Import only the six files ending in .n8n.json into n8n, one at a time. Save each imported workflow.
- Run database-setup.sql in your dedicated application database. Apply the documented grants if setup and n8n use different roles. Run database-smoke-test.sql in a sandbox; its checks roll back.
- Bind the placeholder credentials: Postgres, trusted-backend Header Auth, separate report Header Auth, HubSpot Header Auth, and Google OAuth2. Keep secrets in n8n credentials, never in browser JavaScript.
- Run workflow 03 manually with contact schema read/write access. It creates missing custom properties and refuses incompatible definitions. Keep it manual after setup.
- In workflow 02, Attribution Configuration, set own_domains to your hostnames and leave write_to_hubspot: false. Set review_owner_id if you want an explicit review-task owner.
- In workflow 01, Start Attribution Worker, select your imported workflow 02. In workflow 02, Drain Next Event, select workflow 02 itself. Leave Wait for Sub-Workflow Completion off for both and permit the calls in the worker settings.
- In workflow 04, GA4 Configuration, set the numeric GA4 property ID and its exact timezone. Use the property ID rather than the G-... measurement ID. Set the same property ID in workflow 05, Report Configuration. Workflow 04 defaults to 08:00 Asia/Tbilisi; report boundaries use the GA4 property timezone.
- Select workflow 06 as the error workflow for 01, 02, and 04. These workflow IDs are specific to your n8n instance and must be selected after import.
- Install and adapt website-attribution.js through your normal website deployment. Call capture only after analytics consent. Submit attribution through your trusted backend, which adds the webhook secret and confirms successful submission. The helper does not submit forms or install GA4.
- Save, publish, or activate 01, 02, 04, 05, and 06 as your n8n version requires in your test environment. Use the sample conversion payload with current timestamps and sandbox identities. Manually run the worker and GA4 sync if needed, then inspect proposed CRM changes, audit records, and the report.
- Test first/latest preservation, duplicates, source conflicts, contact creation delays, locks, pagination, and timezone mismatch before enabling CRM writes. Once verified, change write_to_hubspot to true in workflow 02. Earlier dry-run events do not automatically replay into HubSpot.
Integration endpoints
Your trusted backend sends conversions to POST https://YOUR_N8N_HOST/webhook/revops-li-006-conversion with the configured form authentication header. Stored events and identical replays return 202; conflicting reuse of an event UUID returns 409; invalid envelopes return 400.
Read the report at GET https://YOUR_N8N_HOST/webhook/revops-li-006-report with the separate X-Attribution-Report-Secret credential. Never put either secret in public client code. Check snapshot publication time as well as the counts.
Before production
Verify identical replays, shared-submission form/website matching, conflicting email or UTMs, older and newer conversions, a locked source, missing contacts followed by creation, and late events. Validate optional task reconciliation, concurrent database requests, GA4 pagination and property timezone, then compare the report with known test data.
The browser helper needs explicit consent integration and provider-specific adapters for embedded forms or calendars. The operations workflow provides records and counts; configure your own alerts. Follow the full manual for lease recovery and reconcile prior writes before retrying.
Related architecture
Read the Intelligent Lead Routing & Response blueprint for intake and owner routing, and the Revenue Operations Intelligence blueprint for the surrounding qualification and attribution process.
Executable lead intake package
Use the HubSpot Intelligent Lead Routing & Response System to create or update contacts before attribution matching. Forward the same submission_id through both backend event contracts, with a separate stable attribution event_id per producer. Configure the systems independently and test delayed contact creation; importing both packages does not connect their webhooks automatically.
Reviewed duplicate cleanup
Use the HubSpot Duplicate Detection & Approved Merge System for separately configured duplicate review and cleanup. It imports inactive with merge execution disabled. Before combining the packages, test how CRM references reconcile the resulting record ID after an approved merge.
Proposal follow-up
The HubSpot Ghosted Proposal Follow-Up & Recovery System adds separately configured five-to-seven-day check-ins, high-value approvals, and reply tasks. It imports inactive with SMTP delivery disabled.