Ssyncingbeam.app

guides

HubSpot

Validation pending

Production setup or live validation is incomplete. Contact us before using these setup instructions.

The HubSpot connector implementation is present, while production OAuth setup and live validation remain incomplete. This guide documents two aggregate collection modes. Automatic connection prefers verified Analytics API form, page, and traffic-source measures; forms-only mode derives form and normalized-page submission counts when Analytics API is unavailable or deliberately not selected. Views are shown only when HubSpot actually supplies them.

What it is

HubSpot counts form views and submissions on its own servers, so its numbers routinely disagree with GA4's client-side events: consent banners and blocked tags make GA4 undercount. The approved design specifies bringing HubSpot's aggregate marketing numbers into the same per-client store as GA4 and Search Console data so both sides of that disagreement sit in one view, with the discrepancy explained rather than hidden.

Two surfaces are specified: a per-client funnel view (per page and per form) and a section in the monthly report, both fed from the same daily aggregates. A discrepancy audit is designed to show HubSpot submissions next to GA4 form events per page and day, with copy explaining expected mismatches (consent-blocked GA4 tags, server-side vs client-side counting).

What we read

SyncingBeam issues authenticated GET requests only; it does not create, modify, or delete HubSpot records. Authorization goes through HubSpot's OAuth flow using one Projects-based, multi-account app. The same app supports both modes with theforms and business-intelligence scopes. It remains entirely separate from the Google OAuth grant used for GA4 and Search Console: connecting HubSpot would never touch Google credentials, and vice versa. The design stores HubSpot credentials in their own encrypted credential dialect, resolved only by a dedicated HubSpot resolver with no cross-dialect fallback.

The connection screen offers automatic selection and two explicit choices. Automatic selection probes both paths once and chooses the Analytics API only when its required endpoints verify. Explicit choices never silently switch at runtime.

  • Analytics API mode. Daily per-form, per-page, and per-source counts from HubSpot's aggregate analytics endpoints (the forms catalog via the Marketing API, plus daily form, page, and sources breakdowns via the Analytics API). This mode does not request submission rows.
  • Forms aggregation mode. The provider response always contains submitted fields, but the HTTP boundary immediately projects every row to its timestamp and a screened, normalized page path. Submitted values, contact IDs, conversion IDs, raw URLs, and query strings never enter batches, storage, logs, or dead-letter metadata. Bounded worker memory produces only form/day and page/day counts; views and conversion rates remain unavailable rather than being rendered as zero.
  • Channel attribution and submission-level rows. Neither base mode retains submitted UTM fields or contact-linked rows. Those capabilities require a separate privacy and consent decision and are not implied by connecting HubSpot.

Data grain

The canonical grain in the approved design is one row per day, bucketed in the client's reporting timezone (HubSpot timestamps are epoch milliseconds), so HubSpot days line up with GA4 days instead of skewing at every midnight:

  • Per form per day: submissions in both modes; views and conversion rate only in Analytics API mode.
  • Per page per day: keyed by a normalized page key (path only, case-preserved, query and fragment stripped, trailing slash canonicalized) shared with the GA4 side so the funnel join is consistent.
  • Per traffic source per day in Analytics API mode, following the same dimensional conventions as the existing daily tables.
  • Provenance: every canonical form and page row records whether it came from analytics_api orforms_aggregation. The selected mode replaces its exact range transactionally so unlike metric bases are not mixed.

Writes are designed as replace-not-increment: a whole day per stream is fetched, aggregated in memory, and upserted in a single transaction. A crash mid-day commits nothing; a retry recomputes. Scheduled syncs recompute the last three completed client-local days. Analytics history is paced in calendar-month slices; forms history uses one bounded newest-first scan so newer pages are not re-read for every historical month.

Limitations

  • Production activation is not configured. The read-only implementation is present, but the OAuth app and credentials are not configured.
  • Forms aggregation has fewer metrics. It provides form and page submission counts, not views, conversion rates, traffic-source sessions, contacts, customers, or UTM attribution.
  • Modes do not silently fall back. Automatic mode selects once during verified connection. An explicit Analytics API connection reports an actionable error if verification fails.
  • Counts are point-in-time snapshots. If HubSpot processes a GDPR deletion inside the rolling three-day recompute window, recomputed counts shift; outside it, rollups freeze.
  • Legacy analytics endpoints. The primary aggregate endpoints are legacy-flagged by HubSpot, so the design isolates them behind a stream interface that a submissions-derived aggregation could replace without schema change if HubSpot sunsets them.
  • Portal verification still matters. Current HubSpot documentation lists both required scopes for all accounts; it does not support a hard-coded Professional-tier gate. A real portal must nevertheless pass endpoint shape and workbook parity checks before production is called live-verified.

Setup

Production OAuth setup is incomplete. Once the HubSpot OAuth app and scopes are configured, the connect flow is:

  1. An administrator creates one Projects-based multi-account OAuth app, registers the callback, and grants forms plusbusiness-intelligence. SyncingBeam itself performs GET requests only.
  2. An authorized SyncingBeam owner or admin selects Connect HubSpot for the client. The resulting credential is encrypted at rest and is never shared with, or derived from, the Google grant.
  3. Choose automatic, Analytics API only, or forms only. The callback verifies the requested path before the new connector becomes active, so a failed replacement does not pause the working one.
  4. Daily syncs are scheduled automatically; the funnel view and monthly-report section populate as daily aggregates land.

Troubleshooting

These are designed behaviors from the approved spec, described so you know what to expect when the connector ships. They are not observations of a live system.

  • Rate limits and daily quota. The design honors HubSpot's rate-limit headers. On a 429 it reads which policy was exhausted: a per-ten-seconds limit waits and retries within the job; daily-quota exhaustion transitions the job to a scheduled retry at the next daily window with a QUOTA_EXHAUSTED error code. It is never reported as success, and quota deferrals are designed not to consume retry attempts.
  • Revoked access. Portal disconnection or token revocation is a permanent error class: the connector is designed to enter an error status with AUTH_REVOKED surfaced in Settings, the same UX as a Google permission-denied connector today.
  • Today's numbers look low. The current partial day is flagged provisional and recomputed on later syncs, like GA4 intraday data.
  • HubSpot and GA4 disagree. This is expected, and it is what the discrepancy audit is for: HubSpot counts server-side, while GA4 counts client-side behind consent. The design presents both numbers with the explanation instead of forcing them to match.

Sources