Custom HubSpot integrations often start with a simple question:
Can we make HubSpot talk to that other system?
It’s a fair question. But it’s usually not the question that makes or breaks the project.
Most of the time, the API isn’t the hard part. An API is just the doorway software uses to send and receive data. The harder part is deciding who owns the data, what shape it should be in, how reliable the connection needs to be, and who notices when something breaks.
That’s why a good integration project should start with business questions, not code.
If you’re about to pay someone to build a custom HubSpot integration, work through this checklist first.
What problem are we actually solving?
Start by writing the problem in plain English.
Not:
“We need a custom integration.”
Better:
“Sales is retyping customer information into the operations system after every deal is won. Mistakes are slowing down fulfilment, and managers can’t see which jobs are waiting on handover.”
That second version gives you something to design around.
A few good questions to ask:
- which manual task are we trying to remove?
- which mistake are we trying to prevent?
- which report are we trying to make more trustworthy?
- which handover is breaking down?
- who feels the pain today?
- what happens if we do nothing for another three months?
If the answer is vague, the build will probably be vague too.
Is custom really the lightest good-enough option?
A custom integration can be the right answer, but it shouldn’t be the first answer by default.
Before you build, check whether a simpler option gets close enough:
- a native HubSpot app or marketplace integration
- middleware, such as an automation or integration platform
- a HubSpot workflow that updates records or creates tasks
- a scheduled import or export
- a cleaner manual handoff with the right fields and ownership
- a small change to the business process
None of those are a compromise if they solve the real problem with less risk.
This is especially important when the process is still changing. Custom code is easier to justify when the business rule is stable. If the team is still arguing about what should happen after a deal is won, code will just make that uncertainty run faster.
If you’re weighing native sync, middleware and custom code for a specific accounting connection, the same thinking applies to a HubSpot and Xero integration.
Which system is the source of truth?
A source of truth is the system your team trusts when two places disagree.
This is one of the most important integration decisions.
For example:
- HubSpot may own sales activity, pipeline stage, lead source and customer communication
- an accounting system may own invoices, payment status and tax treatment
- an operations platform may own job status, delivery dates and fulfilment notes
- a product database may own SKUs, pricing rules or inventory availability
The answer doesn’t have to be one system for everything. It can be different by record type or field.
The problem comes when nobody decides.
If HubSpot says a company name is one thing and the finance system says another, which one wins? If both systems can update a billing address, what happens when they conflict? If a user edits a field in HubSpot that the other system owns, should the integration overwrite it, ignore it or flag it for review?
Set those rules before the build starts.
What data needs to move?
Don’t start with “sync everything”.
Start with the smallest set of data that supports the process.
HubSpot stores CRM information as records inside objects. Contacts, companies, deals and tickets are common objects. Properties are the fields on those records, such as email, deal amount or service type. Associations are the relationships between records, such as a contact linked to a company or a deal linked to a ticket.
For a custom integration, you need to know which of those pieces matter.
Ask:
- which HubSpot objects are involved?
- do we need contacts, companies, deals, tickets, products, line items, custom objects or activities?
- which properties need to move?
- which properties should never move?
- which records need to be associated with each other?
- do we need historical data, or only new records from go-live?
- which fields are required before a record can sync?
- what should happen with blanks, duplicates and changed values?
This is where many projects get bigger than expected.
The first version of the idea might sound like “send won deals to the operations system”. The real design might involve the deal, company, primary contact, billing contact, line items, service region, owner, quoted amount, delivery notes and a follow-up ticket.
That’s not a reason to avoid the project. It’s a reason to map it properly.
Is the sync one-way or two-way?
One-way sync means data moves from one system into another. Two-way sync means both systems can send updates back.
Two-way sync sounds attractive because it feels complete. It can also create more edge cases.
Before choosing it, ask:
- do users update the same field in both systems?
- what happens if both systems change before the next sync?
- should one system always win?
- do we need a human to approve certain changes?
- do deleted records delete everywhere, archive somewhere, or just stop syncing?
- how will we handle merged contacts or duplicate companies?
A one-way sync with clear ownership is often better than a two-way sync that nobody trusts.
How often does it need to sync?
Not everything needs to happen instantly.
Some integrations should run close to real time. Others can run every few minutes, hourly, overnight or only after a user presses a button.
The right timing depends on the business impact.
Ask:
- does a salesperson need the update during the same call?
- does operations need the handover within minutes, or by the next morning?
- does finance need to approve something before it moves?
- will a high-frequency sync create noise or duplicate work?
- what happens if the other platform is unavailable for a short time?
A webhook is one way systems can react to changes. In simple terms, it’s a message one system sends to another when something happens. Webhooks can reduce constant checking, but they still need somewhere secure to receive the message, plus logging, retries and monitoring.
Real time isn’t automatically better. Reliable and understood is better.
What should happen when something fails?
Every integration fails sometimes.
A field is missing. A record is duplicated. A user changes a value the integration didn’t expect. A credential expires. A platform is temporarily unavailable. An API returns a “slow down” response because the integration has hit a usage limit.
The question isn’t whether failure can happen. It’s whether the business knows what to do when it does.
Define:
- what counts as a failed sync
- where failures are logged
- who gets alerted
- who fixes the record
- whether the integration retries automatically
- how many retries are sensible
- when a human should review the issue
- how the team knows the problem has been resolved
This doesn’t need to be heavy. For a small integration, a simple error log, alert email and weekly health check may be enough.
But it needs to exist.
If nobody owns failures, the integration becomes a quiet source of bad data.
Who owns hosting, monitoring and credentials?
A custom integration has to live somewhere.
That might be a cloud function, a small app, a server, middleware, or infrastructure owned by the business or the agency. The right option depends on the setup, but the ownership needs to be clear.
Ask:
- where will the integration run?
- who pays for the hosting or middleware?
- who can access the logs?
- who gets alerts when it fails?
- where are credentials stored?
- who can rotate or revoke access?
- what happens if a staff member or agency leaves?
HubSpot apps and private app access can be scoped so the app only has the access it needs. That’s good, but it doesn’t remove the need for proper credential handling. Tokens, client secrets and webhook secrets shouldn’t live in someone’s inbox, personal notes or laptop.
The business should know where access lives and who is allowed to manage it.
Who maintains it when people or platforms change?
This is where agency lock-in can sneak in.
Not because every agency is trying to trap you. Most aren’t. But if the build only exists in one developer’s head, the business is exposed.
A healthy custom integration should come with:
- client-owned access to the source code or middleware workspace
- a short explanation of what the integration does
- a list of systems, credentials and owners
- field mapping notes
- error handling notes
- a simple deployment or change process
- a handover plan if the original builder is unavailable
You don’t need a 60-page technical manual for every small integration.
You do need enough documentation that another capable person can understand the setup, make a safe change and recover from a problem.
That isn’t anti-agency. It’s responsible operations.
What reporting do we need from the integration?
A sync doesn’t automatically create better reporting.
It may move the data, but the report still needs definitions.
Ask:
- which report are we trying to improve?
- which team uses it?
- which numbers need to match across systems?
- are we reporting on leads, deals, orders, invoices, revenue, margin, service tickets or fulfilment?
- which date matters: created date, close date, invoice date, paid date or delivery date?
- do managers need a live dashboard, an exception list or a monthly export?
- what should be excluded?
If the integration is meant to support HubSpot reporting, define the report before finalising the data flow.
Otherwise you may move data successfully and still end up with a dashboard nobody believes.
What does done look like?
”The systems are connected” isn’t a strong enough definition of done.
A better definition includes:
- the agreed records and fields sync correctly
- ownership rules are documented
- test cases have passed for normal and edge-case records
- errors are logged somewhere visible
- alerts go to the right person
- credentials are stored properly
- the team knows what to do when something fails
- the business has access to the code, middleware or documentation it needs
- reporting has been checked against real examples
- there is a plan for future changes
Done should mean the integration can survive normal business life, not just a clean demo.
When a custom HubSpot integration is worth it
A custom integration is worth considering when the business rule is real, repeated and valuable.
It may be the right move when:
- native apps don’t support the process clearly enough
- middleware can’t handle the required logic without becoming fragile
- the integration touches several HubSpot objects and associations
- data needs to be transformed before it moves
- approval steps or exception rules matter
- sync failures would cause real operational pain
- reporting depends on a clean, governed data flow
- the business is ready to own hosting, monitoring and support
The point of custom isn’t to build something fancy. It’s to make a business process more reliable than the available off-the-shelf options can.
When it’s probably overkill
Custom is probably overkill when the problem is still unclear, the team doesn’t trust the data, or a simpler process would do the job.
Be careful if:
- nobody can explain the problem without using system names
- the source of truth is unsettled
- the team changes the process every few weeks
- the data is full of duplicates and missing fields
- the sync is mainly wanted because manual discipline is poor
- a native app gets close enough
- a scheduled export would solve the reporting issue
- nobody has time to monitor or maintain the build
In those cases, clean up the process first. Then decide whether custom code is still needed.
A pre-build checklist
Before approving a custom HubSpot integration, ask these questions:
- What problem are we actually solving?
- Is there a native app, middleware, HubSpot workflow or simpler process that gets close enough?
- Which system is the source of truth for each record type and field?
- What data needs to move?
- Which HubSpot objects, properties and associations are involved?
- Is the sync one-way or two-way?
- How often does it need to sync?
- What should happen when something fails?
- Who owns hosting, monitoring and credentials?
- Who maintains it if staff, agencies or platforms change?
- What reports should the integration support?
- What does done look like?
If those answers are clear, the technical build becomes much easier to scope.
If they’re not clear, pause before paying for custom work. You may still need the integration, but you don’t yet have the operating model behind it.
The practical next step
A good custom HubSpot integration isn’t just a connection between systems. It’s an agreement about data, ownership, timing, failure handling and reporting.
Start there.
Map the process. Decide what HubSpot should own. Decide what the other system should own. Choose the simplest connection that supports the operating model.
Sometimes that’s a native app. Sometimes it’s middleware. Sometimes it’s a custom integration.
If you’re considering a custom HubSpot integration and want to sanity-check the plan before the build starts, book a strategy session and we’ll help map the process, risks and next best option.