A custom HubSpot integration for a SaaS product is your own OAuth app on HubSpot's developer platform plus a backend that you run for every customer account that installs it. The build is a few months of focused work. The bigger commitment is the years after launch, because HubSpot retires each API version 18 months after release and every customer's account holds different properties, tiers and validation rules. So the real decision is less "can we build it" and more "who keeps it working for each customer once it ships."
That decision comes up with enterprise deals, where a buyer asks whether your product works inside their HubSpot. Appnigma's done-for-you integrations are built for that case. The offer is "Build your product. We'll build the integrations," with a named integration engineer and ongoing maintenance included. If you are connecting your own company's HubSpot to an ERP or warehouse instead, this page isn't for you. See native, custom and iPaaS HubSpot integrations, or look for a partner in HubSpot's Solutions Directory.
Updated October 2026. Checked against HubSpot's developer platform docs and API usage guidelines. We also checked the Marketplace listing and certification requirements and the September 15, 2026 developer changelog. This update replaces the Developer Account steps and the 100-per-10-seconds limit, corrects which installs count toward listing, separates listing from certification, and removes cost figures and a customer example that were not based on HubSpot sources.
The five parts you run for every customer account
HubSpot hosts your app's configuration and any cards that appear inside HubSpot. Everything else runs on your side, once per installed account. Since March 9, 2026, there is no separate developer account to start from. HubSpot's account types page says "all legacy developer accounts were migrated to standard HubSpot accounts," and new apps are projects created with hs project create per the app creation guide. The current platform version is 2026.09, according to HubSpot's versioning page. Our guide to building a HubSpot app your customers can install covers that setup step by step.
| Part | What it does per customer | The HubSpot rule that shapes it |
|---|---|---|
| Token service | Stores tokens, refreshes before expiry, deletes them on uninstall | Access tokens last 30 minutes |
| Sync engine | Backfills and writes CRM records | 110 requests per 10 seconds per account, batches of 100 |
| Webhook receiver | Takes change events and acknowledges fast | Five-second timeout, up to 10 retries over 24 hours |
| Mapping layer | Maps your data model to that customer's properties and objects | Custom objects need Enterprise, writes follow the account's validation rules |
| Lifecycle handler | Notices installs and uninstalls, cleans up | Uninstall App API required for certification since May 2026 |
The mapping layer is where most of the long-term work lands, and it's the part teams plan least for. Two customers on the same plan can have different required fields. Since API version 2026-09, HubSpot's write validation changelog says it will "enforce admin-configured validation rules on all CRM API write paths," so a write that works for one customer can return a 400 error for the next. Custom object access varies too. The scopes reference marks custom object scopes "Available to Enterprise accounts only," so request them as optional scopes and switch the feature off for accounts that didn't grant them. Our guide to syncing CRM data in every customer's HubSpot account goes deeper on mappings and associations.
The lifecycle handler changed this year. Install and uninstall events now come through an APP_LIFECYCLE_EVENT subscription in HubSpot's webhooks journal API, not the usual webhook file in your project. When a customer disconnects from your side, HubSpot's May 2026 listing changelog says certification submissions "must use the Uninstall App API endpoint." Either way, HubSpot's developer terms require you to "promptly delete all their Content and Customer Data, including all tokens" when a customer asks or leaves.
Rate-limit math for one customer's sync
Every installing account gets its own budget. HubSpot's usage guidelines say "each HubSpot account that installs your app is limited to 110 requests every 10 seconds," with CRM search limited separately. Because the limit is per account, a busy customer can't use up another customer's budget. A single large account can still use up its own. The numbers below are planning arithmetic from those documented limits, not measured benchmarks.
Take a customer who imports 30,000 updated contacts in one afternoon. A polling design finds those changes through the CRM search API. That API allows "five requests per second per account," returns at most 200 records per page and stops at 10,000 results for any query. So the poller needs at least 150 pages, and it has to split the time window into three or more queries because one query can't return more than 10,000 rows. A webhook design receives the same changes as events. The webhooks guide sends up to 100 events per request, and those deliveries "will not count against your app's API rate limits." If your handler then reads the changed records back in batches of 100, that's 300 requests, or about 27 seconds of that account's budget at the full rate.
Tokens affect a second budget that teams rarely track. The usage guidelines say error responses "shouldn't exceed 5% of your total daily requests," and an app "must stay under this 5% limit to be certified." The same page says a 401 response is "not a valid indicator that a new access token must be retrieved." Consider a quiet account where your app makes 400 calls a day. If the app refreshes only after a failure, the 30-minute token lifetime produces up to 48 failed calls a day, which is 12 percent. That account fails the error budget even though nothing is broken. Track each token's expiry and refresh before it runs out.
How long until customers can install it from the Marketplace?
HubSpot doesn't publish build times, but it does publish every step after the build. Engineering estimates vary by scope. Truto's HubSpot architecture guide puts the "Total initial build" at 7 to 12 weeks. The Marketplace clock then runs on customers, not code.
| Milestone | HubSpot's rule | Source |
|---|---|---|
| Pilot installs before listing | Up to 25 accounts, test accounts not counted | Manage apps |
| Submit the listing | Three active installs from unaffiliated production accounts, activity in the past 30 days | Listing requirements |
| First review | Within 10 business days | Listing requirements |
| Apply for certification | After 6 months listed, 60 active installs and enough API traffic | Applying for certification |
| Renew certification | Every two years | Certification requirements |
Two things follow from HubSpot's listing rules. Your own sandboxes and test accounts never count toward the three installs, so three real customers have to be using the integration before you can submit. And certification is optional and comes at least six months after listing, so it doesn't belong on a launch plan. A listed app without the certified badge still installs and works.
The 2027 deadlines that turn into maintenance work
An integration that ships today on numbered API paths has a fixed end date. HubSpot's September 2026 changelog ends support for v1 to v3 APIs and for legacy apps "all with a September 2027 enforcement date." The v4 APIs go unsupported earlier, on March 30, 2027, per the v4 deprecation notice. The changelog's advice is direct. "Do not use v3 or v4 as an intermediate step." Some changes go beyond paths, "including endpoints where the response shape changes."
The penalties hit Marketplace apps specifically. After September 2027, an app calling v1 to v4 "loses its certification status," and an app still on pre-Projects architecture "is eligible for delisting." The new listing rules arrive sooner. From November 2, 2026, the May changelog says apps "using legacy apps or Projects 2023.2 / 2025.1 will be rejected for new listings."
Date-based versions keep this going after 2027. New versions ship every March and September, and the versioning page says each one becomes "unsupported" 18 months after release. So a team that moves to version 2026-09 now has until March 2028 before the next forced move. In practice, every HubSpot integration needs an owner who reads the changelog twice a year and plans an upgrade at least every 18 months. That owner is the line item most build-versus-buy spreadsheets leave out.
Build in-house, use integration infrastructure, or hand it off
A SaaS team can own a customer-facing HubSpot integration in three ways, and the right one depends on where its engineers' time is worth most.
| Route | Who writes the integration logic | Who keeps it working after launch |
|---|---|---|
| Build in-house | Your engineers | Your engineers, on every version change |
| Integration infrastructure (Appnigma's infra, embedded iPaaS, unified APIs) | Your engineers, on the vendor's auth, deployment and monitoring | Shared, depending on the vendor |
| Done for you | A named integration engineer outside your team | The same engineer, under an ongoing engagement |
Build in-house when the HubSpot integration is central to your product and your team can own its lifecycle. Our comparison of building in-house vs Appnigma walks through that case. Infrastructure suits teams that want to write the logic without rebuilding auth, sandboxes and monitoring. Appnigma's integration infra lets "your engineers build the integration logic on Appnigma's infra," and vendors like Merge, Paragon and Truto describe unified API and embedded approaches in our HubSpot integration providers comparison. A handoff suits teams whose roadmap can't absorb customer requests and upgrades. If you mainly need a listed HubSpot app, Appnigma's marketplace apps projects deliver "a native app, marketplace listing preparation, and review support."
Whichever route you choose, settle one question early. Whose HubSpot app ID will your customers install? The listing requirements say a listed app must authorize requests with "the public HubSpot app ID (and OAuth client ID) associated with your app listing." They also say the listing "must not redirect to a different public or private app or require another public or private app to function." If you plan to list, the app should live in an account you control, with the tokens it creates, even when someone else writes the code.
Mistakes that surface after the first customers install
Each of these mistakes breaks a documented HubSpot rule, and each one usually shows up only after real customers have installed the app.
- Counting your own sandboxes or test accounts toward the three listing installs.
- Sending search calls through the same limiter as everything else. Search has its own limit of five requests per second.
- Refreshing tokens only after a
401, which spends the 5 percent error budget. - Requesting custom object scopes as required, which blocks installs on accounts below Enterprise.
- Building on v3 or v4 paths in a new integration, then migrating twice before September 2027.
- Treating HubSpot-side uninstalls as rare. HubSpot's certification guidance says that if 100 percent of requests return
401and the refresh fails, "consider the app uninstalled."
For the certification review itself, see our guide to HubSpot app certification requirements.
Frequently Asked Questions
What is a HubSpot custom integration for a SaaS product?
It's your own OAuth app on HubSpot's developer platform, plus a backend that syncs data for every customer account that installs it. A shared connector app from another vendor can't serve as your Marketplace listing.
Do I still need a HubSpot developer account?
No. HubSpot migrated developer accounts into standard accounts on March 9, 2026, and you create apps as projects with the HubSpot CLI.
What rate limit does a HubSpot Marketplace app get?
110 requests every 10 seconds for each installing account, with CRM search limited separately to five requests per second. Webhook deliveries don't count against either limit.
Do I need HubSpot certification to list my integration?
No. Listing needs three active installs from unaffiliated production accounts. Certification is optional and needs six months listed with 60 active installs.
Can Appnigma build and maintain our HubSpot integration?
Yes. Appnigma's done-for-you service assigns a named integration engineer who builds the integration and keeps it working as HubSpot's APIs change. Your engineers can also build on Appnigma's integration infra instead.
About the author
Sunny Chauhan is the co-founder and CEO of Appnigma AI, which builds and maintains customer integrations and native Salesforce and HubSpot apps for B2B SaaS teams. Before Appnigma, he was on Salesforce's AppExchange team, where he worked with more than 300 SaaS partners. He has spent close to a decade on the Salesforce platform, including work at Zennify, and holds Salesforce certifications including Platform Developer II, Platform App Builder, Administrator, Data Cloud Consultant, and AI Associate.
Related Articles
- How to build a HubSpot app your customers can install
- How to build a HubSpot CRM integration that works in every customer's account
- HubSpot app certification requirements
- HubSpot integration providers and services
- Native, custom and iPaaS HubSpot integrations explained
Sources
- HubSpot account types and Create an app, HubSpot Developers
- Developer platform and API versioning, HubSpot Developers
- API usage guidelines and limits, HubSpot Developers
- CRM search and Webhooks API, HubSpot Developers
- OAuth scopes and Webhooks journal subscriptions, HubSpot Developers
- App listing requirements and Manage apps, HubSpot Developers
- Applying for certification and Certification requirements, HubSpot Developers
- Legacy APIs and legacy apps, what's going unsupported and when and Deprecating support for v4 APIs, HubSpot Developer Changelog
- CRM API write validation enforcement and Listing and certification updates for May 2026, HubSpot Developer Changelog
- HubSpot Developer Terms, HubSpot Legal
