How does a HubSpot integration actually work?

"Integration" gets used for three quite different things, which is why the answers people get are so inconsistent.

Here is what is actually happening underneath, in plain terms, and the three shapes it comes in.

What an integration is doing#

Strip away the vocabulary and every integration does the same four things.

1. Reads records that changed in system A.
2. Matches each one to a record in system B, using an identifier both sides share.
3. Transforms the fields so they mean the same thing on both sides.
4. Writes the result into system B, creating the record if it is not there.

Step 2 is where integrations succeed or fail. Everything else is mechanics.

The matching problem, which is the whole game#

Two systems have to agree on what makes two records the same record.

HubSpot matches contacts on email address by default. That works until a person changes jobs, or uses a shared inbox, or your ERP keys on a customer number that has nothing to do with email.

What a well built integration does instead is store the other system's ID on the HubSpot record as a property, typically called something like erp_customer_id. Then every write is an upsert keyed on that value: update the record if one with this ID exists, create it if not.

The payoff is that re-running the sync is safe. Run yesterday's data again and you get the same result, not a second copy of everything. Without a stable ID, every retry risks duplicates, and duplicate cleanup costs more than the integration did.

If the other system genuinely has no stable ID, agreeing a composite key is the first thing to settle, before anyone writes code.

One way or two way, and why the second costs triple#

One way means one system is the source of truth for a given field. Orders flow from the ERP into HubSpot, and nothing flows back. Simple, predictable, and correct for most cases.

Two way means both systems can change the same field, which introduces a question with no default answer: when both changed since the last sync, who wins?

You need conflict rules, last write timestamps, and loop prevention so that HubSpot writing to the ERP does not trigger the ERP writing back to HubSpot forever. That is roughly triple the work of one way sync, and most teams that ask for two way actually need one way in each direction on different fields, which is a much easier problem.

Decide this field by field, not system by system.

The three ways to build it#

A marketplace app. Someone already built the connector. Install it, authenticate, map a few fields. If a well reviewed app covers your systems and your field mapping, use it. It costs a subscription instead of a project and it is maintained for you.

Where it stops: apps sync the objects and fields their author chose. Custom objects, unusual mappings, and business logic between the two systems are usually outside what they do.

A custom private app. You create a private app inside HubSpot, it gives you an access token with specific scopes, and your own service calls the API using it. This is what you build when the mapping is specific to your business.

What goes into a serious one: retries with backoff, idempotent writes, a dead letter queue for records that fail repeatedly, and alerting that fires when expected data does not arrive rather than only when something errors.

A file based pipeline. The other system's only outbound interface is a scheduled CSV on an SFTP server. This is far more common in manufacturing, logistics and finance than vendors admit.

It is a real integration, not a downgrade. Schema validation on arrival, keyed upserts, row level error reporting, and a quarantine report a non developer can act on. Slower than an API, equally reliable.

What triggers a sync#

Scheduled. Runs every fifteen minutes, or nightly. Simple and predictable. Fine when data being an hour old is acceptable, which it usually is.

Webhook. The source system calls your service the moment something changes. Near real time, and it needs a queue behind it so a burst does not drop records.

Most integrations should be scheduled. Real time is a requirement people assert and rarely need, and it roughly doubles the operational surface.

What it looks like when it is running#

A healthy sync produces a visible artifact, even when nothing is wrong:

Run 02:00 UTC
  14,208 rows read
   1,046 created
  13,158 updated
       4 quarantined  -> see exception report

Four quarantined rows out of 14,208 is normal. Zero every single day usually means validation is not running.

What you should get at the end#

Code in your repository, credentials in your accounts, and a runbook covering how to reprocess a failed batch, what each quarantine reason means, and who resolves it.

An integration only the vendor can operate is not a deliverable. The full six stage sequence is here, and the thing that most often makes it worth building is the portal being coherent in the first place.

Frequently asked questions#

How long does a HubSpot integration take to build?#

Three to eight weeks for a custom one. A marketplace app is an afternoon. The variable is the historical backfill and the reconciliation that proves both systems agree, not the connection itself.

Do I need a developer to integrate HubSpot?#

Not if a marketplace app covers your systems and field mapping. You do once the mapping is specific to your business, once custom objects are involved, or once logic has to sit between the two systems.

What is a HubSpot private app?#

An app you create inside your own portal that issues an access token with specific scopes. It is how a custom integration authenticates, and it replaced API keys, which HubSpot has retired.

Can HubSpot integrate with a system that has no API?#

Yes, through a file based pipeline. A scheduled CSV to SFTP or S3, validated on arrival and upserted on a stable key, is a completely workable integration surface.