Using Custom Objects in a HubSpot–Salesforce Integration: A RevOps Playbook

Standard objects carry you far—Contacts, Companies/Accounts, Deals/Opportunities, Campaigns. But modern motions increasingly depend on data that does not fit neatly into those shapes: subscriptions, implementations, partner agreements, assets, usage events, entitlements. When you need to model these business concepts first‑class, custom objects become the backbone of your go‑to‑market data.

This playbook shows how to design, govern, and operate custom objects across HubSpot and Salesforce so they improve execution and reporting without exploding your surface area for failure. We emphasize durable identity keys, lean relationships, and pragmatic sync patterns.

When to Use a Custom Object

Reach for a custom object when a concept has:

— A stable identity and lifecycle (it changes over time but remains the same “thing”).

— Distinct permissions or owners (e.g., customer success, partnerships) that differ from sales or marketing.

— Reporting value on its own (e.g., active subscriptions by tier, implementations by stage).

— Associations to standard objects that are neither one‑off nor purely descriptive fields.

If your concept is a one‑time attribute of an existing object (e.g., an extra field on a Deal), you do not need a custom object—favor a field and a process. Custom objects should earn their existence.

A Decision Framework You Can Reuse

Ask five questions before you create the object: (1) Does this concept have a stable identity that persists across quarters? (2) Does it need separate permissions from the standard objects? (3) Will we report on it directly, not only as context for another object? (4) Are there clear, durable associations to Contacts, Accounts, Deals, or Campaigns? (5) Can we define a compact lifecycle? If you answer yes to at least three and you can state the object’s purpose in one sentence, proceed. If not, keep the data where it lives and improve the process that consumes it.

Deep Dive: Identity and Associations

Identity must survive renames, merges, and vendor changes. External keys are stronger than internal IDs; composites built from stable attributes are stronger than names. For associations, choose purposeful links. An “Implementation” links to exactly one Account, optionally to a primary Contact, and may link to the selling Opportunity for revenue context. Resist the urge to add every plausible association. Extra links confuse users and slow reports; only link what you use.

When you do need many‑to‑many relationships, create a join object with a role. For example, “Contact ↔ Implementation Role” could capture Champion, Project Manager, or Technical Owner. Keep the role list short and define which roles count toward lifecycle signals and alerts.

Governing the Model

Assign an owner for the custom object—someone who decides semantics, fields, and lifecycle. Give that owner a backlog and a quarterly review slot with RevOps, sales operations, and customer success. In the review, remove fields that no longer drive decisions, clarify status definitions, and verify that alerts and dashboards are still relevant. Without an owner, custom objects become junk drawers.

Projecting Between Systems

Treat one system as SOR for each attribute and project a lean subset into the other for visibility, segmentation, or workflow triggers. For example, if Salesforce is SOR for “Subscription” financials, project only Tier, Seat Count, Status, and Renewal Date to HubSpot. Avoid projecting cost, vendor IDs, or sensitive notes unless there is a clear use case. If HubSpot is SOR for onboarding communications, project the communication status back to Salesforce so CSMs see it in their flow.

Lifecycle Examples

Compact lifecycles are easier to reason about. For “Implementation,” six statuses often suffice: Planned, Kickoff Scheduled, In Progress, Blocked, Live, Closed. Each transition should have a crisp criterion and an owner. Capture timestamps on entry and exit. Emit a small event on transitions so downstream systems can react (e.g., trigger a customer celebration email when Live begins).

Reporting Patterns That Unlock Decisions

Custom objects shine when they power decisions. Subscriptions enable visibility into ARR by tier, approaching renewals, and potential expansions. Implementations reveal onboarding load, blockers, and average time to value. Expose one dashboard per audience—CS leaders see capacity and risk; sales leaders see expansion opportunities by segment; marketing sees entitlement for campaigns. Keep charts tied to lifecycle and identity to avoid drift.

Performance Considerations

Custom objects multiply records and queries. Index the fields you filter on (status, key dates, SOR keys) and keep payloads small when syncing. For bulk updates, use batch endpoints with conservative sizes and backoff. If you project the object to both systems, do so asynchronously with idempotent writes and checkpoints. Monitor object growth and storage; set a pruning policy for stale or test records.

Migration Case Study: Implementations

A SaaS company tracked onboarding milestones in spreadsheets, which created blind spots for CSMs and marketing. The team modeled “Implementation” as a custom object with ID, Account Key, Primary Contact, Status, Start Date, Live Date, Owner, and Notes. Salesforce became SOR; HubSpot received a projection (Status, Start/Live dates) for segmentation and lifecycle emails. They backfilled a year of history, created a small runbook for status changes, and added a dashboard showing time in Blocked. Within two months, average time to Live dropped by nine days, and marketing’s adoption campaigns targeted the right customers precisely.

Operational Maturity Model

Stage 1 (Ad hoc): Teams paste IDs into spreadsheets; no consistent status. Stage 2 (Model established): Custom object exists with identity and lifecycle; projections exist but are manual. Stage 3 (Integrated): Events drive emails and alerts; dashboards aligned to decisions; owners assigned. Stage 4 (Optimized): Lifecycle metrics feed forecasts; expansion playbooks tie to object signals; quarterly hygiene removes unused fields. Aim to move one stage at a time; do not jump from ad hoc to optimized in a single sprint.

Avoiding Common Traps

Two traps recur. First, over‑modeling—adding fields because they “might help later.” Each field adds cost and drift; require a use case before adding it. Second, under‑securing—projecting sensitive attributes into broad‑access systems. Audit who can see what, and restrict fields accordingly. If you catch yourself adding a sensitive attribute “for convenience,” step back and ask whether a narrower projection would suffice.

Backfill Strategy

Backfills are where theory meets reality. Start by generating identity keys for historical records from the source system. Create the custom objects in the SOR first; then, in small batches, project them to the other system. Reconcile associations carefully: for each record, link to the correct Account by Account Key and, if needed, to the primary Contact. Verify a sample on both sides before running the next batch. Keep a checkpoint so a partial failure does not require starting over.

Maintaining Calm at Scale

As custom objects grow, so does the temptation to bolt on exceptions. Resist. Create overlays for edge cases (a flag or extra property) rather than forking the entire object. Review associations quarterly and remove links not used in reports or automation. Keep the lifecycle compact and infrequently changed; stability helps teams trust dashboards and alerts.

Automation in Both Systems

Design automations that do one thing well and tolerate retries. In Salesforce, prefer Flows for straightforward field updates and task creation; reserve Apex for complex logic or performance‑sensitive paths. In HubSpot, use workflows with narrow triggers based on status or key dates. Tag integration‑originated changes so you can avoid loops and double‑actions. Always include a guard condition that checks whether the desired state already exists before writing.

Alerts Your Team Will Thank You For

Alert on states, not just changes. For “Implementation,” alert when Blocked lasts more than N days, when Live is overdue by more than M days from Start, and when no owner is assigned for more than 24 hours. For “Subscription,” alert when a renewal date falls within 60 days without an open opportunity, or when usage drops below a threshold for a sustained period. Tie alerts to owners and provide a direct link to the object record.

Sunsetting a Custom Object

Sometimes the best integration work is subtraction. If a custom object no longer drives decisions, plan a sunset. Freeze creation, move essential attributes to a standard object if appropriate, capture a final export for historical analysis, and remove projections and automation. Communicate the change and update dashboards to prevent head‑scratching months later when charts go blank. Sunsetting keeps your CRM powerful rather than ponderous.

Documenting Custom Objects Clearly

Extend your data dictionary with a section for each custom object: identity key, relationships (with cardinality and roles), authoritative attributes, projection attributes, lifecycle definitions, and owners. Include two example records—one typical, one edge case—with values for each field. Link to the runbooks that mention the object and to the dashboards that visualize it. When you add or change a field, update this section as part of the same change record.

Security Audits and Access Reviews

Quarterly, run an access review for custom objects. Confirm that only teams who need the object can view or edit it, and that sensitive fields (prices, terms, PII) are restricted. Validate that the integration user has only the minimal privileges required. In HubSpot, verify team‑based permissions on the object and properties; in Salesforce, check field‑level security, record type visibility, and sharing rules. Access reviews are dull—and they prevent embarrassing incidents.

Training and Enablement

Add a short onboarding module for each custom object covering its purpose, lifecycle, who owns it, and where it shows up in the UI. Include a one‑page “how to update” guide with screenshots and rules of engagement (what to change, what never to change). Teach managers how to use the dashboards built on the object so coaching aligns with your model. Reinforce with quick reference cards.

Data Quality for Custom Objects

Quality drift shows up in status misuse, missing identity keys, and stale owners. Add monthly checks for each: status distribution with outliers, percentage of records missing keys, and number of unassigned records by age. When you find problems, adjust processes rather than creating one‑off fixes—tighten allowed values, add pre‑save checks, or update automation to assign owners immediately.

Modeling the Object

Start with the concept’s single sentence definition and the decisions it will inform. Identify the minimal attribute set required for those decisions. Add identity first: a durable external key (e.g., SUBSCRIPTION_ID) and any secondary keys (e.g., vendor ID) you need for reconciliation.

Keep the model small: identity, status, dates, owner, and a handful of attributes used in segmentation or reporting. Additional fields can be added after the object proves its value in operations.

Relationships Without Regret

Define associations to standard objects explicitly and sparingly. An implementation relates to a Company (the customer), possibly to a primary Contact, and sometimes to a Deal/Opportunity that sold it. Prefer one‑to‑many relationships. If you must model many‑to‑many, use roles to reduce ambiguity and avoid a combinatorial explosion of associations.

When joining across systems, anchor relationships on durable keys rather than only on Salesforce IDs or HubSpot internal IDs. Store the partner system’s external key on the object itself so the integration can reconcile without brittle lookups.

Designing in HubSpot vs Salesforce

HubSpot custom objects enable CRM‑native views, automation, and reporting; Salesforce custom objects unlock the full platform of validation, flows, and Apex. If sales process and revenue reporting are primary, model the source of truth in Salesforce and mirror a lean projection in HubSpot. If marketing automation relies on the object heavily (e.g., lifecycle triggers from subscription status), consider HubSpot as source for those attributes while Salesforce remains SOR for billing or entitlement details. Document where each attribute is authoritative.

Identity and Keys

Give the object a single, immutable external key. Build this key from vendor IDs when available or a deterministic composite (e.g., ACCOUNT_KEY + SKU + START_DATE). Avoid keys that depend on mutable attributes like names or free‑form text. Store secondary identifiers for cross‑system reconciliation but never rely on them for identity.

Sync Patterns That Don’t Collapse Under Load

Choose a sync pattern per attribute:

— One‑way projection: copy authoritative fields from SOR to the other system for visibility and segmentation.

— Event‑driven updates: when a status changes, emit an event rather than diffing entire records. Downstream workflows respond to events.

— Periodic reconciliation: run a daily/weekly job that compares counts and spot‑checks identity joins, repairing drift in batches.

Bidirectional updates for the same field are rare and fragile; document and test them explicitly when they truly matter.

Lifecycle and Status Design

Give the custom object a compact lifecycle (5–7 statuses) and define entry/exit criteria. Examples for “Implementation”: Planned, Kickoff, In Progress, Blocked, Live, Closed. Attach timestamps for transitions so you can measure duration and quality. Emit a small event when status changes so reports and alerts update without polling.

Automation With Restraint

Automation is where custom objects become useful—or overwhelming. In both systems, design workflows that do one thing well and are idempotent. For example, when an Implementation moves to “Kickoff,” create tasks for onboarding, notify the owner, and set a due date. If the record is updated twice, the automation should not double‑create tasks. Tag integration writes and respect that tag in flows to avoid loops.

Security and Privacy

Custom objects often contain sensitive details: contract terms, entitlements, usage. Apply least privilege and segment by team where possible. In Salesforce, restrict field‑level access to sensitive attributes (e.g., cost) and use record types or sharing rules for teams. In HubSpot, use team permissions and property‑level restrictions to align visibility with need‑to‑know.

Reporting That Matters

Define the object’s core KPIs before you build the model. For “Subscription,” you might track active count, churned count, ARR by tier, and renewal dates due. For “Implementation,” you might track time to kickoff, average days in Blocked, and time to Live. Keep dashboards focused on decisions: where to put resources, which risks to escalate, and what to celebrate.

Migration and Backfill

If you introduce a new custom object into a live go‑to‑market, you must migrate historical data and relationships. Backfill identity keys first, then create objects in the SOR, and finally project them to the other system. For relationships, build a deterministic join (e.g., by Account Key and date range) and run in batches with checkpoints. Validate a sample thoroughly before moving to full volume.

Operating the Object Long‑Term

Treat custom objects as products. Assign an owner, maintain a backlog, and run a monthly hygiene review: field usage, picklist drift, orphaned relationships, and record growth. Review the lifecycle definitions quarterly and kill attributes that no longer drive decisions.

Example: Subscriptions as a Custom Object

Suppose you sell software subscriptions and want reps to see entitlement at a glance while marketing segments campaigns by tier and renewal risk. Model “Subscription” in Salesforce as SOR with fields for Tier, Seats, ARR, Start Date, End Date, and Status. In HubSpot, project Tier, Seats, Status, and Renewal Date for segmentation and nurture. Emit an event when Status changes; trigger a renewal workflow in HubSpot and update a dashboard in Salesforce. Identity is SUBSCRIPTION_ID from your billing system; relationships include Account and the primary Contact. This projection gives sellers context and marketers leverage without leaking sensitive billing details into every system.

FAQ

How do I know a custom object is the right choice versus a new field?

If the concept has its own lifecycle, owners, and reporting needs—and if it relates to multiple standard objects—choose a custom object. If it is only an attribute of a single object and does not drive independent decisions, keep it as a field.

Can we maintain bidirectional sync on custom object fields?

It is possible but fragile. Prefer one system as SOR and project to the other. Where true bi‑direction is required (e.g., a task checklist), isolate those fields, document conflict rules, and test heavily.

How should we handle many‑to‑many relationships?

Introduce a join object with roles and minimal attributes. Resist proliferating associations that are not used in reporting or workflows. Keep the role list short and document which roles count for lifecycle and KPIs.

What is the best way to generate keys if no vendor ID exists?

Use a deterministic composite built from stable attributes (e.g., ACCOUNT_KEY + CANONICAL_SKU + START_DATE). Hash it if needed. Avoid names and free text. Once set, treat the key as immutable.

How do we prevent automation loops between systems?

Tag integration writes and have both HubSpot workflows and Salesforce Flows/Apex check the tag. Use idempotent patterns—create‑or‑update with a unique key—so retries do not duplicate side effects.