How do you build a custom HubSpot integration?
Create an app on HubSpot's developer platform, authenticate with OAuth or a static auth token, and call HubSpot's dated REST APIs to read and write records. Subscribe to webhooks so HubSpot tells you when records change instead of polling. For simple, workflow-driven jobs, HubSpot's Send a webhook and custom code actions may be enough without a full app.
This guide follows HubSpot's developer documentation as of October 2026, a year of big platform changes. If you only need to connect two apps, check for a Marketplace app or a tool like n8n first.
How does HubSpot API authentication work now?
Apps on HubSpot's developer platform use OAuth when installed in several accounts, or a static auth token when installed in a single account. HubSpot stopped new legacy private apps for new accounts in September 2026 and existing accounts on 26 October 2026, and offers service keys, in public beta, as the replacement. OAuth access tokens expire after 30 minutes.
- Existing private apps keep working for now; HubSpot plans to stop supporting legacy apps from September 2027.
- Projects: new apps are built as projects on a platform version, currently 2026.09.
- Secrets: store tokens and keys outside your code and rotate them when people leave.
What rate limits and versions should you design around?
Privately distributed apps get 100 requests per 10 seconds on Free and Starter and 190 on Professional and Enterprise, within daily account limits; Marketplace apps get 110 per 10 seconds per account. The CRM search API allows five requests a second and 10,000 results per query. APIs now use dated paths, such as /2026-09/, each supported for 18 months.
| App type and tier | Per 10 seconds | Per day, per account |
|---|---|---|
| Private, Free or Starter | 100 | 250,000 |
| Private, Professional | 190 | 625,000 |
| Private, Enterprise | 190 | 1,000,000 |
| Marketplace app | 110 per account | Not stated |
Use batch endpoints, which take up to 100 records per request, cache what you can, and back off on 429 responses. HubSpot asks that errors stay under 5% of requests. Plan to move from v1 to v4 paths to dated versions: HubSpot says v1 to v3 become unsupported after September 2027.
How do you receive HubSpot webhooks reliably?
Subscribe your app to the events you need, such as contact creation or deal property changes, and HubSpot posts batches of up to 100 events to your URL. Validate the v3 signature and reject timestamps older than five minutes, respond within five seconds, then process asynchronously. Expect duplicates and events out of order, and deduplicate on your side.
- 01 ReceiveHTTPS endpoint
- 02 Validatev3 signature, timestamp
- 03 AcknowledgeWithin five seconds
- 04 QueueProcess asynchronously
- 05 DeduplicateEvents can repeat
- 06 FetchLatest record if needed
- Retries: failed deliveries are retried up to ten times over 24 hours.
- Limits: up to 1,000 subscriptions per app, and webhook deliveries don't count against API limits.
- Platform apps configure webhooks in project files, and HubSpot's webhooks journal API offers another way to read events.
When are workflow webhooks or custom code enough?
When a HubSpot workflow is the trigger and the job is contained. On Data Hub Professional or Enterprise, Send a webhook posts all or chosen properties to an HTTPS endpoint and retries for up to three days, though not after most 4XX errors. Custom code actions run JavaScript or Python for up to 20 seconds with 128 MB of memory.
Build a full app when you need two-way sync, many accounts, or logic that doesn't fit a workflow. Whichever route, document field ownership and alerting; our integration governance guide covers what to agree.
Planning a custom HubSpot integration? Bring the systems and data to a free 30-minute call and we will sketch the architecture.
Custom HubSpot integration checklist
Key takeaway: Build new integrations on HubSpot's developer platform with dated APIs, respect rate limits with batching and backoff, and treat webhooks as at-least-once events you validate and deduplicate.
Frequently asked questions
How do you authenticate a custom HubSpot integration in 2026?
With OAuth for apps installed in more than one account, or a static auth token for an app installed in a single account, built on HubSpot's developer platform. HubSpot stopped new legacy private apps for existing accounts on 26 October 2026 and offers service keys, in public beta, as their replacement.
What are HubSpot's API rate limits?
When we checked in October 2026, privately distributed apps could make 100 requests per 10 seconds on Free and Starter and 190 on Professional and Enterprise, with daily account limits of 250,000, 625,000 and 1,000,000 respectively. Marketplace apps get 110 requests per 10 seconds per account, and the CRM search API allows five requests per second.
What is HubSpot's date-based API versioning?
Since March 2026, HubSpot's APIs use dated versions in the path, such as /2026-09/, instead of v1 to v4. New versions arrive in March and September, each supported for 18 months. HubSpot says v1 to v3 endpoints become unsupported after September 2027, and current v4 APIs are supported until March 2027.
How do HubSpot webhooks work?
An app subscribes to events such as contact creation or property changes, and HubSpot posts batches of events to your URL. Validate the signature, respond within five seconds, and expect duplicates and events out of order. HubSpot retries failed deliveries up to ten times over 24 hours.
When should you use workflow webhooks instead of the API?
When the trigger is a HubSpot workflow and the job is simple. On Data Hub Professional or Enterprise, the Send a webhook action posts record data to your HTTPS endpoint and retries for up to three days. For several steps or calls back into HubSpot, use a custom code action or a full app.
Sources
HubSpot documentation behind the feature and tier notes above, checked October 2026. HubSpot changes features and tiers often, so check your own portal too.
- Authentication overview (HubSpot developers)
- Legacy private app creation sunset (HubSpot changelog)
- Account service keys (HubSpot developers)
- API usage guidelines and limits (HubSpot developers)
- Introducing date-based API versioning (HubSpot changelog)
- Legacy APIs and apps: what's going unsupported and when (HubSpot changelog)
- Search the CRM (HubSpot developers)
- Webhooks guide (HubSpot developers)
- Validate requests (HubSpot developers)
- Use webhooks with HubSpot workflows
- Error handling (HubSpot developers)