.png)
HubSpot Sales Hub Integration Guide
Integrate HubSpot Sales Hub with enterprise systems through REST APIs, OAuth 2.0, private app tokens, webhooks, batch APIs, imports, and file services.
HubSpot Sales Hub integration options at a glance
HubSpot Sales Hub uses HubSpot’s REST APIs as its primary integration surface for Contacts, Companies, Deals, Products, Line items, Quotes, associations, imports, files, and platform services. OAuth 2.0 supports multi-account applications, while private app access tokens suit integrations dedicated to one HubSpot account. Webhooks provide notifications for configured object and event subscriptions, and batch endpoints and the Imports API support bulk processing. GraphQL can query selected data, although REST has broader CRM coverage. Martini can consume these APIs, receive and validate webhook notifications, orchestrate workflows, transform data, and apply retry, reconciliation, and idempotency rules.
| Integration point | Supported by HubSpot Sales Hub? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Create, read, update, and archive Contacts, Companies, Deals, Products, Line items, Quotes, and other HubSpot objects; search data; manage associations, imports, files, pipelines, and property definitions. | Martini can consume HubSpot REST endpoints from workflows, map request and response payloads, follow pagination, and expose reusable APIs around the integration. |
| GraphQL APIs | Limited | Query selected HubSpot data through GraphQL when the required objects and fields are available in the current schema. | Martini can consume GraphQL APIs and transform the returned data, while REST should remain the default when broader CRM coverage is required. |
| Webhooks and outbound callbacks | Yes | Receive notifications for configured Contact, Company, Deal, creation, archival, property-change, and selected association events. | Martini can expose an API endpoint to receive webhook requests, validate signatures, acknowledge promptly, and start an idempotent workflow that retrieves current HubSpot state. |
| Bulk, asynchronous, and batch APIs | Yes | Process bulk object creation, reading, updating, and archiving, and perform larger or structured data loads through HubSpot batch endpoints and the Imports API. | Martini can orchestrate batch requests, inspect per-object results, retry transient failures, and persist migration or synchronization checkpoints. |
| File and attachment APIs | Yes | Upload and manage files through HubSpot Files, then associate file identifiers with supported Contacts, Companies, Deals, Tickets, Quotes, or other objects. | Martini can transfer files, map metadata, call association APIs, and coordinate downstream document distribution workflows. |
| Authentication | Yes | Use OAuth 2.0 for multi-account applications or private app access tokens for integrations dedicated to one HubSpot account. API keys are deprecated for new implementations. | Martini can store credentials in environment configuration or secrets management and use authenticated API workflows without embedding tokens in workflow definitions. |
| Analytics and reporting APIs | Limited | Retrieve reporting and analytics data for dashboards, metrics, and business reporting; these APIs differ from operational CRM object APIs. | Martini can consume relevant reporting endpoints and route analytical data separately from operational Contact, Company, and Deal synchronization. |
| Database access | No | HubSpot does not provide a customer-facing relational database or direct SQL interface for Sales Hub data access. | Martini should use HubSpot REST, GraphQL where suitable, and reporting or analytics APIs rather than attempting direct database connectivity. |
How HubSpot Sales Hub exposes data and business events
HubSpot Sales Hub REST APIs
HubSpot REST APIs are the primary integration mechanism for Sales Hub. They cover CRM object lifecycle operations, search, associations, property and pipeline metadata, imports, files, communications, and other platform services.
Martini implementation pattern
Martini consumes the required HubSpot endpoints from workflows or reusable APIs. It authenticates with OAuth 2.0 or a private app token, follows pagination, maps properties and associations, and stores synchronization state for incremental processing and recovery.
Implementation sequence
HubSpot Sales Hub GraphQL APIs
HubSpot provides GraphQL for querying selected HubSpot data. Its object and field coverage must be checked against the current schema because GraphQL does not replace the broader REST CRM surface.
Martini implementation pattern
Martini can consume HubSpot GraphQL queries when the required data is available and use workflow transformations to normalize the response. REST remains the preferred fallback for unsupported objects, mutations, or broader CRM operations.
Implementation sequence
HubSpot Sales Hub Webhooks
HubSpot webhooks notify subscribed applications about configured event types and selected changes to Contacts, Companies, Deals, and other supported objects. They are subscription-specific and do not represent every possible Sales Hub event.
Martini implementation pattern
Martini exposes an API endpoint to receive the notification, validates the HubSpot signature, acknowledges promptly, and starts a workflow that retrieves authoritative current state. Durable state, duplicate detection, and reconciliation handle retries and out-of-order delivery.
Implementation sequence
HubSpot Batch and Imports APIs
HubSpot provides batch CRM endpoints and an Imports API for bulk object operations and larger structured data loads. Batch responses can contain both successful and failed records.
Martini implementation pattern
Martini uses scheduled or manually initiated workflows to partition workloads, submit batch or import requests, inspect individual outcomes, and retry only eligible failures. Checkpoints make migrations and recurring loads restartable.
Implementation sequence
HubSpot Files API
HubSpot’s Files API supports uploading and managing files. Uploading a file and associating it with a Contact, Company, Deal, Ticket, Quote, or other supported object are separate integration concerns.
Martini implementation pattern
Martini transfers the document, captures the resulting HubSpot file identifier or URL, and invokes the applicable association operation. The workflow can also retrieve file metadata and distribute documents to another repository.
Implementation sequence
Common HubSpot Sales Hub integration patterns
Pattern 1: Synchronize Contacts and Companies
When to use this pattern
Use this pattern when HubSpot Sales Hub must share customer and account information with another CRM, ERP, data warehouse, or customer database. It supports both scheduled reconciliation and reverse updates through a Martini API or workflow.
Integration direction
Example Mapping
| HubSpot Sales Hub Field | Canonical Field | Target Field |
|---|---|---|
| HubSpot Contact ID | externalContactId | Salesforce Contact.External_Id__c |
| personEmail | Salesforce Contact.Email | |
| HubSpot Company ID | externalCompanyId | Salesforce Account.External_Id__c |
| lifecycle stage | customerLifecycleStage | Salesforce Contact.Lead_Status__c |
Martini implementation pattern
A scheduled Martini workflow queries changed Contacts and Companies using paging or search filters, resolves associations, validates required fields, and applies create-versus-update rules. It persists HubSpot and target identifiers, handles conflicts according to system-of-record policy, and uses webhook-triggered updates for selected low-latency changes.
Martini capabilities used
- workflows
- API consumption
- scheduling
- data mapping
- business rules
- state management
- error handling
Pattern 2: Convert Deals into ERP transactions
When to use this pattern
Use this pattern when a HubSpot Deal reaching a qualifying pipeline stage should create or update a customer, quote, sales order, or invoice in an ERP such as NetSuite. The flow must include associated Products, Line items, Companies, and Contacts where required.
Integration direction
Example Mapping
| HubSpot Sales Hub Field | Canonical Field | Target Field |
|---|---|---|
| Deal ID | sourceOpportunityId | NetSuite externalId |
| Deal amount | transactionTotal | NetSuite total |
| Deal stage | transactionStatus | NetSuite orderStatus |
| Line item quantity | quantity | NetSuite item quantity |
Martini implementation pattern
Martini receives a selected Deal webhook or retrieves qualifying Deals on a schedule, then fetches current Deal associations and commercial objects. It maps pipeline stages, validates currency and line-item data, creates or updates the NetSuite transaction, and writes the external identifier or processing status back to HubSpot. A deterministic Deal key prevents duplicate orders.
Martini capabilities used
- webhooks
- workflows
- API orchestration
- association resolution
- data transformation
- business rules
- idempotency
- retry handling
Pattern 3: Trigger downstream sales automation
When to use this pattern
Use this pattern when selected Contact, Company, or Deal changes should notify Slack, create a Jira issue, update a support process, or initiate another enterprise workflow without polling for every change.
Integration direction
Example Mapping
| HubSpot Sales Hub Field | Canonical Field | Target Field |
|---|---|---|
| Deal stage | eventType | Slack message category |
| Deal name | subject | Slack message title |
| Deal owner | responsibleUser | Slack message context |
| HubSpot Deal ID | sourceObjectId | deduplication key |
Martini implementation pattern
HubSpot sends a configured webhook notification to a Martini API endpoint. Martini validates the signature, acknowledges promptly, retrieves current object state, applies event and channel rules, and publishes a notification or invokes a downstream API. Duplicate and out-of-order events are controlled with durable keys and current-state retrieval.
Martini capabilities used
- API exposure
- webhook consumption
- workflows
- business rules
- data mapping
- duplicate prevention
- monitoring
Pattern 4: Load HubSpot data into an analytical store
When to use this pattern
Use this pattern for recurring extraction of CRM and engagement data into Snowflake or another analytical environment for revenue reporting, attribution, forecasting, and reconciliation.
Integration direction
Example Mapping
| HubSpot Sales Hub Field | Canonical Field | Target Field |
|---|---|---|
| Deal ID | dealId | sales_deals.deal_id |
| Company ID | companyId | sales_deals.company_id |
| amount | dealAmount | sales_deals.amount |
| hs_lastmodifieddate | modifiedAt | sales_deals.modified_at |
Martini implementation pattern
A scheduled Martini workflow uses incremental filters or stored timestamps, follows HubSpot paging cursors, normalizes object properties and associations, and loads staged data into Snowflake. It records extraction checkpoints, isolates malformed objects, retries throttled requests, and periodically performs reconciliation for missed or changed data.
Martini capabilities used
- scheduled workflows
- REST API consumption
- pagination
- data transformation
- database integration
- checkpointing
- error handling
Applications commonly integrated with HubSpot Sales Hub
HubSpot Sales Hub can be integrated with adjacent business applications for CRM coexistence, financial processing, customer support context, implementation workflows, notifications, commerce activity, and analytics. Martini can orchestrate these flows through each system’s supported APIs, webhooks, files, and authentication methods without requiring a dedicated HubSpot connector.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Contacts, Companies or Accounts, Leads, and Deals during CRM coexistence, migration, or departmental integration. | HubSpot Sales Hub → Martini → Salesforce | Use scheduled REST synchronization or selected HubSpot webhook triggers, resolve associations, apply system-of-record rules, map CRM properties, and persist external identifiers to prevent duplicate updates. |
| NetSuite | Convert HubSpot Deals and associated Products or Line items into customers, sales orders, invoices, or other financial records. | HubSpot Sales Hub → Martini → NetSuite | Retrieve the Deal and its associated commercial objects, transform pipeline stages and amounts into NetSuite structures, create or update the financial record, and return the NetSuite identifier or status to HubSpot. |
| Microsoft Dynamics 365 | Synchronize sales accounts, contacts, and opportunities when business units use HubSpot Sales Hub and Dynamics 365 together. | HubSpot Sales Hub → Martini → Microsoft Dynamics 365 | Combine webhook notifications with scheduled reconciliation, map Companies and Contacts to account and contact models, map Deals to opportunities, and apply explicit ownership and conflict rules. |
| Shopify | Bring customer, order, and commerce activity into HubSpot Sales Hub for sales visibility and use selected HubSpot lifecycle data in commerce processes. | Shopify → Martini → HubSpot Sales Hub | Consume Shopify events or APIs, normalize customer and order data, match customers using stable identifiers, and create or update HubSpot Contacts, Companies, or associated activity according to lifecycle rules. |
| Zendesk | Share customer, company, and support context between sales and support teams while keeping Zendesk tickets and HubSpot Tickets distinct where required. | Zendesk → Martini → HubSpot Sales Hub | Retrieve Zendesk ticket and requester data, match it to HubSpot Contacts or Companies, update selected HubSpot properties or activities, and use validation to avoid treating the two ticket models as equivalent. |
| Jira | Create or update Jira issues from HubSpot Deals, Tickets, or workflow events for implementation, onboarding, and product escalation. | HubSpot Sales Hub → Martini → Jira | Trigger from selected HubSpot events or a scheduled query, map the business context into a Jira issue, store the Jira key against the HubSpot object, and synchronize status changes where required. |
| Slack | Publish notifications for new Deals, stage changes, escalations, or support events to selected Slack channels. | HubSpot Sales Hub → Martini → Slack | Receive configured HubSpot webhook events, retrieve current object state, apply channel and severity rules, and send a formatted notification while deduplicating retried events. |
| Snowflake | Load HubSpot CRM and engagement data into a central analytical environment for revenue reporting, attribution, and forecasting. | HubSpot Sales Hub → Martini → Snowflake | Run paginated or batch extraction workflows, normalize object properties and associations, stage data for loading, track cursors and extraction timestamps, and support reconciliation of failed loads. |
How to build a HubSpot Sales Hub integration in Martini
Objective
Establish the HubSpot authentication model and protect credentials according to whether the integration serves one HubSpot account or multiple accounts.
Instructions in Martini
- Choose OAuth 2.0 for multi-account authorization or a private app access token for a dedicated account
- Configure scopes or private-app permissions for the required CRM objects, files, webhooks, and reporting APIs
- Store tokens, client secrets, refresh tokens, and webhook secrets in Martini environment configuration or secrets management
- Configure the target application authentication separately
Objective
Select the event, schedule, or API entry point that starts the integration and supports both low-latency processing and recovery.
Instructions in Martini
- Use configured HubSpot webhook notifications for selected object changes
- Use a scheduler for incremental synchronization and reconciliation
- Use a Martini API when an external application needs to submit or request HubSpot-related work
- Define how webhook notifications and scheduled recovery interact
Objective
Obtain authoritative HubSpot data rather than relying only on notification payloads, and retrieve the associations required by the business process.
Instructions in Martini
- Call the relevant REST endpoint or GraphQL query
- Follow paging cursors and store progress for long-running loads
- Retrieve Contacts, Companies, Deals, Products, Line items, Quotes, or activities as required
- Resolve associations explicitly because object properties do not automatically include all relationships
Objective
Coordinate HubSpot calls, target-system calls, enrichment, validation, and state management in a maintainable Martini workflow.
Instructions in Martini
- Separate webhook acknowledgement from longer downstream processing where appropriate
- Route records according to object type, stage, lifecycle, or business event
- Use reusable workflow logic for common authentication, lookup, and error paths
- Persist source and target identifiers, timestamps, and processing status
Objective
Convert HubSpot properties and relationship structures into the target application’s canonical model while handling HubSpot-specific data types.
Instructions in Martini
- Map custom properties and standard properties to canonical fields
- Convert date-times, currency amounts, enumerations, booleans, nulls, and multi-select values explicitly
- Normalize Contacts, Companies, Deals, Products, Line items, and Quotes into the target structure
- Preserve HubSpot IDs and association references for traceability
Objective
Enforce validation, ownership, lifecycle, stage, duplicate, and system-of-record rules before writing data to another system.
Instructions in Martini
- Validate required properties and association completeness
- Map HubSpot pipeline and deal stages to target statuses
- Use search-before-create or deterministic external IDs where duplicate creation is possible
- Define handling for archived, deleted, rejected, and partially valid objects
Common HubSpot Sales Hub data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Contacts | Represent people involved in sales activity, communications, companies, and deals. | Salesforce, Microsoft Dynamics 365, NetSuite, Snowflake, Zendesk | Martini retrieves or receives change notifications, maps properties, resolves associations, validates identifiers, and creates or updates the target contact model. |
| Companies | Represent organizations or accounts associated with Contacts, Deals, and other CRM objects. | Salesforce, Microsoft Dynamics 365, NetSuite, Snowflake | Martini synchronizes company properties and association relationships, applies account matching rules, and stores external identifiers for idempotent updates. |
| Deals | Track sales opportunities through HubSpot pipelines and deal stages. | NetSuite, Salesforce, Microsoft Dynamics 365, Jira, Snowflake | Martini retrieves current Deal state, maps pipeline and stage values to target statuses, enriches the payload with associated objects, and prevents duplicate downstream transactions. |
| Products | Maintain products or services in the HubSpot product library. | NetSuite, Salesforce, Snowflake | Martini maps product identifiers, descriptions, prices, and custom properties to downstream catalogs or commercial structures and handles changed or archived products. |
| Line items | Represent individual products or services associated with Deals, Quotes, or other commercial objects. | NetSuite, Salesforce, Snowflake | Martini retrieves Line items with their associations, converts quantities and currency values, and validates them before creating orders, quotes, or analytical facts. |
| Quotes | Represent commercial quotations containing Line items and associations with Contacts, Companies, and Deals. | NetSuite, Salesforce, document repositories, Snowflake | Martini synchronizes quote properties and relationships, transfers related files when required, and applies approval or status rules before downstream processing. |
Authentication and security considerations
Authentication choices
HubSpot Sales Hub supports OAuth 2.0 for public or multi-account applications and private app access tokens for integrations dedicated to one HubSpot account. API keys are deprecated for new implementations.
Credential protection
OAuth access and refresh tokens, private app tokens, client secrets, and webhook signing secrets should be stored in Martini environment configuration or secrets management rather than embedded in workflows.
Webhook validation
Webhook consumers should validate HubSpot request signatures before accepting events. OAuth scopes and private-app permissions should be limited to the objects and services required by the integration.
Operational considerations for HubSpot Sales Hub integrations
Throttling and pagination
HubSpot applies account- and application-level limits. Handle HTTP 429 responses and Retry-After guidance, control concurrency, prefer batch endpoints where suitable, and follow paging cursors until the required data is processed.
State and idempotency
Store synchronization timestamps, cursors, source identifiers, target identifiers, and processing status. Use HubSpot object IDs or dedicated external ID properties to prevent duplicate creates and make retries safe.
Webhooks and reconciliation
Webhook subscriptions cover selected events and deliveries can be retried or arrive out of order. Treat notifications as triggers to retrieve current state, then run scheduled reconciliation to recover missed or failed events.
Schema and lifecycle changes
HubSpot administrators can change custom properties, pipelines, stages, required fields, and association labels. Design mappings to be configurable where possible and define how archived or deleted objects are represented downstream.
Testing and monitoring
Test authentication, pagination, associations, partial batch failures, file associations, throttling, and webhook retries. Monitor workflow logs and retain correlation identifiers for troubleshooting API-version or schema changes.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini coordinates HubSpot API calls, webhook intake, target-system operations, transformations, business rules, and recovery behavior in managed workflows rather than scattering logic across one-off scripts.
Reusable integration assets
Teams can expose controlled Martini APIs, reuse workflow logic, and maintain common authentication, validation, mapping, and error-handling behavior across HubSpot integrations.
Reliable synchronization
Martini supports scheduled, event-driven, batch, and API-led designs. Durable state, idempotency rules, retries, and monitoring make synchronization easier to operate than independent point-to-point jobs.
Flexible implementation
REST is the primary HubSpot integration surface, while GraphQL, webhooks, batch operations, imports, and files can be introduced where appropriate. Martini can also apply custom transformation logic when standard mappings are insufficient.
Frequently asked questions
HubSpot Sales Hub can be integrated through its REST APIs, OAuth 2.0, private app access tokens, configured webhooks, batch and Imports APIs, Files API, and selected GraphQL queries. REST supports operational synchronization of Contacts, Companies, Deals, Products, Line items, Quotes, associations, and other platform data.
Yes. Martini can consume HubSpot REST APIs, use GraphQL where the required data is supported, receive and validate HubSpot webhook notifications, process batch and import operations, and upload or manage files through HubSpot APIs. No native Martini HubSpot connector is verified in the supplied documentation.
No. A dedicated HubSpot connector is not required. Martini can integrate using HubSpot’s native REST APIs, GraphQL queries where appropriate, webhooks, batch and Imports APIs, Files API, OAuth 2.0, or private app access tokens.
Lonti does not charge an additional per-connector or per-vendor fee to integrate HubSpot Sales Hub. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from HubSpot, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
Use REST APIs as the primary method for CRM objects, associations, search, imports, files, and operational synchronization. Use webhooks for selected near-real-time events, batch or Imports APIs for bulk movement, private app tokens for a single account, OAuth 2.0 for multi-account applications, and GraphQL only when its current schema provides the required data.
Yes. HubSpot supports webhook subscriptions for selected object and event types, including configured Contact, Company, and Deal changes. Martini can expose an API endpoint, validate the webhook signature, acknowledge promptly, retrieve current HubSpot state, and process duplicate or out-of-order notifications. Coverage is subscription-specific rather than universal.
A typical design combines webhook triggers with scheduled REST reconciliation. Martini follows pagination, stores synchronization state, retrieves authoritative object data, resolves associations separately, and maps HubSpot properties into a canonical or target model. Explicit conversions are needed for dates, currency, enumerations, booleans, nulls, and multi-select values.
Martini workflows can validate payloads, handle HTTP 429 responses and retry timing, control concurrency, retry transient failures, and inspect individual results from batch operations. Durable synchronization keys based on HubSpot IDs or external ID properties prevent duplicate writes, while webhook signature validation and current-state retrieval reduce the impact of repeated or out-of-order events.
Related Martini documentation
HubSpot APIs
Workflows
Data handling
Integrate HubSpot Sales Hub with Martini
Use Martini to connect HubSpot Sales Hub APIs and webhooks with your enterprise applications through maintainable workflows, secure authentication, data mapping, and reliable synchronization.