Ellipse Gradient for Header
HubSpot Marketing Hub logo

HubSpot Marketing Hub Integration Guide

Connect HubSpot Marketing Hub with enterprise systems through REST APIs, selected webhooks, batch imports, files, and secure OAuth or private app authentication.

HubSpot Marketing Hub integration options at a glance

HubSpot Marketing Hub is primarily integrated through its versioned REST APIs, which cover CRM objects, associations, properties, search, forms, marketing email, lists, files, imports, and related services. Selected CRM and application events can be delivered through HubSpot webhooks, although coverage varies by object, event, subscription, and account. Batch endpoints and import APIs support larger data loads, while the Files API supports file management. Martini can consume these endpoints, receive supported webhook notifications, schedule incremental synchronization, map HubSpot JSON into enterprise models, apply consent and business rules, and expose controlled APIs for downstream applications. OAuth 2.0 and private app access tokens provide the principal authentication options.

Integration pointSupported by HubSpot Marketing Hub?Common use casesHow Martini supports it
REST APIsYesHubSpot’s primary interface for Contacts, Companies, Deals, Forms, Marketing emails, Lists, associations, properties, search, files, imports, and other Marketing Hub services.Martini can consume HubSpot REST endpoints from workflows, parse JSON responses, map properties, orchestrate related calls, and expose normalized APIs.
Webhooks / outbound callbacksLimitedSelected CRM and application events can notify an integration about object creation, deletion, property changes, or selected marketing and subscription events.Martini can expose an HTTPS API endpoint or webhook-consuming workflow, validate notifications, deduplicate them, and process substantial work asynchronously.
Bulk / async / batch APIsYesBatch CRM operations and import APIs support larger contact, company, deal, and other supported object loads, subject to endpoint-specific limits and response behavior.Martini can partition payloads, invoke supported batch or import endpoints, inspect item-level results, and retry or route partial failures.
File / attachment APIsYesThe Files API supports file upload and management; association of files with CRM or marketing objects depends on the relevant HubSpot API.Martini can upload, retrieve, and route files through REST workflows while preserving HubSpot file identifiers and association results.
GraphQL APIsLimitedHubSpot documents GraphQL primarily for selected CMS and content experiences, not as the general API for Marketing Hub CRM data.Martini can consume GraphQL where a confirmed HubSpot CMS use case requires it, while using REST for Contacts, Companies, Deals, Forms, Marketing emails, and Lists.
AuthenticationYesOAuth 2.0 supports public or multi-account applications, while private app access tokens support controlled server-to-server integrations for a known HubSpot account.Martini can keep credentials in secrets, send Bearer tokens, support token refresh workflows, and separate authentication failures from insufficient-scope responses.
SOAP APIsNot confirmedNo current supported SOAP API was confirmed for new HubSpot Marketing Hub integrations.Martini should use HubSpot REST APIs and supported webhook mechanisms rather than assuming a SOAP interface.
Database accessNoHubSpot does not provide direct relational database access for customer integrations; analytics data must use supported APIs or exports.Martini can load supported HubSpot data into an enterprise database or warehouse but should not connect to HubSpot’s underlying database.

How HubSpot Marketing Hub exposes data and business events

HubSpot REST APIs

HubSpot’s versioned REST APIs are the primary integration surface for Marketing Hub. They cover CRM objects, associations, properties, search, forms, marketing email, lists, imports, files, and other product areas, with availability varying by object, account, and subscription.

Martini implementation pattern

Martini implementation pattern: a workflow authenticates with OAuth 2.0 or a private app token, calls the required REST resources, follows pagination, maps HubSpot JSON into a canonical model, applies business rules, and writes to one or more target systems.

Implementation sequence

Authenticate with an OAuth 2.0 token or private app access token
Call the required HubSpot REST resource
Follow pagination and preserve continuation state
Resolve required associations and properties
Map HubSpot JSON into the target model
Apply validation, consent, and ownership rules and write the result

HubSpot Webhooks

HubSpot supports webhook-style notifications for selected CRM and application events, including some object creation, deletion, property-change, marketing, and subscription scenarios. Coverage is selective and must be verified for each required event.

Martini implementation pattern

Martini implementation pattern: expose a controlled HTTPS API endpoint, validate the incoming notification, acknowledge promptly, deduplicate using an event identifier or deterministic key, then retrieve the current HubSpot resource when the event payload is incomplete.

Implementation sequence

Receive the HubSpot webhook notification
Validate the request and identify the event type
Acknowledge the delivery promptly
Deduplicate the event using a stable key
Retrieve the current HubSpot resource when required
Route the normalized event to downstream systems and record processing status

HubSpot Batch and Import APIs

HubSpot provides batch endpoints for supported CRM object operations and import APIs for larger contact, company, deal, and other supported loads. Each endpoint has its own limits, request structure, and response behavior.

Martini implementation pattern

Martini implementation pattern: a scheduled or API-triggered workflow partitions source data, submits supported batches or imports, interprets accepted and item-level results, and stores checkpoints for retries and reconciliation.

Implementation sequence

Select the supported batch or import operation
Partition the source data within HubSpot limits
Submit the batch or import request
Inspect item-level success and failure results
Retry recoverable failures with bounded backoff
Persist checkpoints and reconcile incomplete loads

HubSpot Files API

HubSpot’s Files API supports file upload and management. Whether a file can be attached or associated with a particular CRM or marketing object depends on the applicable API and account permissions.

Martini implementation pattern

Martini implementation pattern: a workflow receives or retrieves a file, authenticates to the Files API, uploads it, captures the resulting file identifier, and performs a separate supported association step when required.

Implementation sequence

Receive or retrieve the source file
Validate file type, size, and metadata
Upload the file through the HubSpot Files API
Store the returned HubSpot file identifier
Create a supported object association when required
Record the result and route failures for retry or review

HubSpot GraphQL APIs

HubSpot documents GraphQL capabilities primarily for selected CMS and content experiences. GraphQL is not the primary general-purpose interface for Marketing Hub Contacts, Companies, Deals, Forms, Marketing emails, or Lists.

Martini implementation pattern

Martini implementation pattern: use a GraphQL-consuming workflow only for a confirmed CMS or content requirement, while keeping general Marketing Hub synchronization on REST APIs and applying the same mapping, validation, and error-handling controls.

Implementation sequence

Confirm that the required HubSpot data is exposed through GraphQL
Configure the GraphQL request and authentication
Submit the query from a Martini workflow
Validate and map the response
Apply business rules and write the target result
Use REST APIs for unsupported Marketing Hub CRM requirements

Common HubSpot Marketing Hub integration patterns

Pattern 1: Sync HubSpot contacts and companies with an enterprise CRM

When to use this pattern

Use this pattern when marketing and sales teams need synchronized customer and account data across HubSpot and an enterprise CRM. It supports scheduled incremental reads, selected webhook events, or a controlled reverse flow from the CRM.

Integration direction
HubSpot Marketing Hub
Martini
Salesforce
Example Mapping
HubSpot Marketing Hub FieldCanonical FieldTarget Field
HubSpot Contact idcontact.externalIdSalesforce Contact.External_Id__c
HubSpot Contact emailcontact.emailSalesforce Contact.Email
HubSpot Contact lifecycle stagecontact.lifecycleStageSalesforce Contact.Lifecycle_Stage__c
HubSpot Company nameorganization.nameSalesforce Account.Name
Martini implementation pattern

A scheduled Martini workflow uses HubSpot search with modification timestamps and supported webhook events as an acceleration path. It retrieves associations, validates consent and required properties, matches by governed identifiers, performs idempotent upserts, and sends recoverable failures to bounded retry handling or an operational queue.

Martini capabilities used
  • workflows
  • API consumption
  • scheduling
  • data mapping
  • business rules
  • validation
  • error handling

Pattern 2: Route HubSpot form submissions to operational systems

When to use this pattern

Use this pattern when form submissions must create or update downstream leads, cases, tasks, or operational work without relying on manual exports. The exact event mechanism must be confirmed for the selected HubSpot form and subscription.

Integration direction
HubSpot Marketing Hub
Martini
Jira
Example Mapping
HubSpot Marketing Hub FieldCanonical FieldTarget Field
HubSpot Form submission emaillead.emailJira issue.customfield_contactEmail
HubSpot Form submission page URLlead.sourceUrlJira issue.description
HubSpot Contact lifecycle stagelead.lifecycleStageJira issue.labels
HubSpot Form submission timestamplead.submittedAtJira issue.customfield_submittedAt
Martini implementation pattern

Martini receives a supported notification or polls the applicable submissions API, validates and normalizes the payload, applies routing and duplicate rules, creates or updates the downstream item, and records the HubSpot identifier and target key for safe retries.

Martini capabilities used
  • webhook handling
  • API consumption
  • workflows
  • data mapping
  • validation
  • business rules
  • error handling

Pattern 3: Synchronize consent-aware marketing audiences

When to use this pattern

Use this pattern when Contacts, Companies, or Lists must be delivered to an advertising, messaging, or customer data platform while preserving subscription and consent controls. Lists, dynamic segments, and subscription states should be treated as distinct concepts.

Integration direction
HubSpot Marketing Hub
Martini
Snowflake
Example Mapping
HubSpot Marketing Hub FieldCanonical FieldTarget Field
HubSpot List membershipaudience.membershipSnowflake audience_membership
HubSpot Contact emailperson.emailSnowflake person_email
HubSpot subscription statusconsent.statusSnowflake consent_status
HubSpot Contact lastmodifieddatesource.modifiedAtSnowflake source_modified_at
Martini implementation pattern

A scheduled Martini workflow retrieves supported Lists and contact properties, filters by region, consent, lifecycle stage, and account status, transforms the output into a controlled audience model, and rejects or quarantines records with missing consent data. The workflow checkpoints pages and reconciles membership changes.

Martini capabilities used
  • scheduling
  • API consumption
  • data mapping
  • business rules
  • validation
  • JSON handling
  • error handling

Pattern 4: Load HubSpot marketing and revenue data into a warehouse

When to use this pattern

Use this pattern when marketing email, campaign, Contact, Company, Deal, and association data is needed for attribution, revenue reporting, or operational dashboards. API coverage and reporting granularity depend on the HubSpot account and subscription.

Integration direction
HubSpot Marketing Hub
Martini
Snowflake
Example Mapping
HubSpot Marketing Hub FieldCanonical FieldTarget Field
HubSpot Deal idopportunity.externalIdSnowflake deal_id
HubSpot Deal amountopportunity.amountSnowflake deal_amount
HubSpot Marketing email idcampaign.emailIdSnowflake marketing_email_id
HubSpot Deal lastmodifieddatesource.modifiedAtSnowflake modified_at
Martini implementation pattern

Martini schedules paginated and incremental REST reads, retrieves required associations, normalizes object-specific schemas, writes warehouse-ready batches, and stores a checkpoint per object and endpoint. Periodic full or scoped reconciliation detects missed webhook events, archive changes, and association drift.

Martini capabilities used
  • scheduling
  • API consumption
  • workflow orchestration
  • data mapping
  • batch processing
  • checkpointing
  • monitoring
  • error handling

Applications commonly integrated with HubSpot Marketing Hub

HubSpot Marketing Hub can be integrated with adjacent business applications when organizations need consistent customer, marketing, commercial, support, or analytical data. The exact direction and object coverage should be governed by ownership, subscription, permissions, and the APIs available in each environment.

Application Scenario Direction Martini Pattern
Salesforce Synchronize Contacts, Companies or Accounts, Leads, Opportunities, campaign responses, and lifecycle data between marketing and sales operations. HubSpot Marketing Hub → Martini → Salesforce Martini consumes HubSpot REST APIs or selected webhook events, resolves associations, applies field ownership and consent rules, and performs idempotent Salesforce upserts with bounded retries.
ServiceNow Send customer and company context or qualified form activity to ServiceNow and return selected case or service-status information to HubSpot. HubSpot Marketing Hub → Martini → ServiceNow A Martini workflow receives or polls HubSpot data, validates identifiers and consent fields, maps the payload to ServiceNow APIs, and records correlation IDs and retry status.
NetSuite Align HubSpot contacts, companies, qualified leads, and commercial or revenue-related information with NetSuite customer and transaction processes. NetSuite → Martini → HubSpot Marketing Hub Martini schedules incremental reads from NetSuite and HubSpot, normalizes customer and revenue attributes, applies source-of-truth rules, and writes only supported HubSpot objects or properties.
Microsoft Dynamics 365 Exchange Contacts, Accounts, Leads, Opportunities, and marketing qualification data across marketing and commercial teams. HubSpot Marketing Hub → Martini → Microsoft Dynamics 365 Martini orchestrates bidirectional API calls, maps HubSpot properties and associations to Dynamics entities, prevents duplicate creation, and routes validation or permission failures for review.
Jira Create or update Jira issues from form submissions, campaign operations, or other HubSpot events and return issue status where needed. HubSpot Marketing Hub → Martini → Jira A Martini webhook or scheduled workflow validates the HubSpot event, applies routing rules, creates Jira issues through its API, and stores the Jira key against the originating HubSpot identifier.
Zendesk Share customer and contact context with support teams and use selected support activity in customer-success or marketing workflows. Zendesk → Martini → HubSpot Marketing Hub Martini retrieves or receives Zendesk changes, matches contacts using governed identifiers, maps support status without overwriting consent, and updates supported HubSpot objects through REST APIs.
Shopify Synchronize customers, products, orders, and commerce events with HubSpot Contacts, Companies, Lists, and marketing workflows where the configured APIs support the required data. Shopify → Martini → HubSpot Marketing Hub Martini consumes commerce events or scheduled API data, normalizes customer and order identifiers, applies audience and consent rules, and performs supported HubSpot writes with reconciliation.
Snowflake Load HubSpot Contacts, Companies, Deals, marketing activity, and campaign data into an analytical warehouse for attribution and revenue reporting. HubSpot Marketing Hub → Martini → Snowflake Scheduled Martini workflows use paginated REST, search, batch, or supported export mechanisms, preserve associations and timestamps, transform records into warehouse models, and checkpoint incremental loads.

How to build a HubSpot Marketing Hub integration in Martini

Objective

Establish the HubSpot connection with the least privilege required for the integration and keep environment-specific credentials outside workflow definitions.

Instructions in Martini

  • Choose OAuth 2.0 for multi-account or administrator-consented integrations, or a private app token for a known account
  • Store access tokens, refresh tokens, and private app tokens in Martini secrets
  • Configure portal identifiers, scopes, API settings, and target credentials per environment
  • Handle authentication failures separately from insufficient-scope responses

Objective

Select an event-driven or scheduled entry point based on the HubSpot object and event coverage required by the solution.

Instructions in Martini

  • Use a Martini API or webhook-consuming workflow for supported HubSpot notifications
  • Use a scheduler for incremental synchronization, reconciliation, or APIs without suitable webhook coverage
  • Confirm the selected HubSpot subscription and event type before relying on webhook delivery
  • Use a start trigger that captures correlation and source metadata

Objective

Obtain the complete HubSpot resource and related data needed for processing rather than assuming a notification contains the full business object.

Instructions in Martini

  • Call the relevant REST resource after a webhook notification when the payload is incomplete
  • Follow pagination until the response indicates that no further page exists
  • Use search, modification timestamps, batch endpoints, or imports for supported incremental and larger loads
  • Retrieve associations and required properties explicitly

Objective

Coordinate HubSpot calls, target-system calls, validation, routing, and state management in a maintainable Martini workflow.

Instructions in Martini

  • Separate retrieval, normalization, business rules, target writes, and status recording into clear workflow stages
  • Use reusable integration logic for common authentication, pagination, matching, and error handling
  • Keep source identifiers, correlation IDs, and checkpoints with the workflow state
  • Use asynchronous processing when webhook work is substantial

Objective

Convert HubSpot’s account-specific properties and JSON structures into a stable canonical or target model.

Instructions in Martini

  • Map standard and custom HubSpot properties explicitly
  • Normalize dates, enumerations, amounts, identifiers, and association labels
  • Preserve HubSpot object IDs and consent or subscription fields
  • Validate required fields and route malformed or schema-changing payloads for review

Objective

Enforce ownership, consent, deduplication, and routing rules before writing to another system or changing HubSpot data.

Instructions in Martini

  • Define the authoritative identifier and source of truth for each object
  • Prevent duplicate Contacts, Companies, audience members, or downstream tasks
  • Do not overwrite consent as a side effect of unrelated Contact updates
  • Apply account, region, lifecycle, subscription, and data-quality rules

Common HubSpot Marketing Hub data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
ContactsIndividuals, lifecycle stages, consent properties, marketing communication, and CRM activity.Salesforce, Microsoft Dynamics 365, Snowflake, Zendesk, ShopifyMartini reads or receives supported changes, validates identifiers and consent, maps properties, resolves associations, and performs idempotent upserts.
CompaniesOrganizations associated with contacts, commercial activity, and account-level segmentation.Salesforce, Microsoft Dynamics 365, NetSuite, SnowflakeMartini synchronizes standard and custom properties, applies account matching rules, and handles association creation separately from company updates.
DealsCommercial opportunities, revenue synchronization, campaign attribution, and lifecycle reporting.Salesforce, Microsoft Dynamics 365, NetSuite, SnowflakeMartini retrieves supported deal properties and associations, transforms stages and amounts, and loads downstream systems with checkpointed incremental processing.
Marketing emailsMarketing email definitions and delivery or engagement-related data where the applicable API and permissions provide access.Snowflake, reporting platforms, customer data platformsMartini calls the relevant Marketing Hub APIs, normalizes campaign and engagement fields, and preserves timestamps and account-specific identifiers.
FormsLead capture definitions and submitted form data for downstream processing.Salesforce, Microsoft Dynamics 365, Jira, SnowflakeMartini consumes supported submission data or retrieves it through APIs, validates required fields, applies routing rules, and records the HubSpot submission or contact ID.
ListsContact or company audience segments for targeting, suppression, and operational synchronization.Advertising platforms, customer data platforms, SnowflakeMartini retrieves supported list membership or audience data, distinguishes static and dynamic segmentation, applies consent rules, and synchronizes only supported downstream representations.

Authentication and security considerations

Use OAuth 2.0 or private app tokens

Use OAuth 2.0 when the integration must connect to multiple HubSpot accounts or obtain administrator consent. Use a private app access token for a controlled integration tied to one known account. Legacy API keys are not appropriate for new implementations.

Protect credentials and scopes

  • Store access tokens, refresh tokens, and private app tokens in Martini secrets.
  • Request only the scopes required by each workflow.
  • Separate read-only and write-capable credentials where practical.
  • Handle expired tokens, invalid tokens, and insufficient scopes as distinct conditions.

Govern marketing data

Consent, subscription status, opt-in and opt-out timestamps, and related legal-basis fields should be treated as governed data. Do not overwrite consent as an incidental effect of a general Contact synchronization.

Operational considerations for HubSpot Marketing Hub integrations

Rate limits and pagination

HubSpot applies usage limits based on account, application, endpoint, and subscription. Martini workflows should detect 429 responses, respect retry timing, use bounded backoff, avoid unbounded parallelism, and prefer supported batch operations. Collection APIs should be paginated until no next page remains.

Idempotency and associations

Define authoritative identifiers and safe create, update, or upsert behavior for each object. Preserve HubSpot IDs, retrieve associations explicitly, and deduplicate webhook deliveries using an event identifier or deterministic key.

Schema and subscription variation

Properties, custom fields, event coverage, API availability, and permissions can differ between HubSpot accounts. Version mappings, validate enumerations and data types, and confirm the connected subscription supports each required capability.

Reliability and observability

  • Use scheduled reconciliation because webhook coverage and delivery can be partial.
  • Inspect item-level errors from batch and import operations.
  • Capture HTTP status, HubSpot error details, object type and ID, correlation data, workflow execution ID, and retry count.
  • Test with environment-specific portals, apps, scopes, properties, and webhook subscriptions before production deployment.

Why use Martini instead of scripts or point-to-point integrations?

Centralize integration behavior

Martini provides a governed workflow layer for HubSpot API calls, webhook intake, scheduled synchronization, transformations, target writes, and operational state. This avoids duplicating authentication, pagination, retry, and mapping logic across point-to-point scripts.

Keep mappings and rules maintainable

HubSpot properties and associations can vary by account. Martini workflows make validation, consent handling, source-of-truth decisions, canonical models, and reusable integration logic explicit and maintainable.

Support reliable enterprise operations

Instead of treating an HTTP success response as completion, Martini can inspect item-level results, apply bounded retries, preserve checkpoints, route exceptions, and expose controlled APIs for other applications. The same implementation can combine real-time notifications with scheduled reconciliation.

Frequently asked questions

How can HubSpot Marketing Hub be integrated with enterprise systems?

HubSpot Marketing Hub is primarily integrated through its REST APIs for Contacts, Companies, Deals, Forms, Marketing emails, Lists, associations, files, imports, and search. Selected CRM and application events can be delivered through webhooks, while batch and import APIs support larger loads. OAuth 2.0 and private app access tokens provide the main authentication options.

Can Martini integrate with HubSpot Marketing Hub?

Yes. Martini can consume HubSpot REST APIs, receive supported HubSpot webhook events through a Martini API or workflow, schedule incremental synchronization, map HubSpot JSON, and expose controlled APIs for downstream applications. A native Martini HubSpot connector is not confirmed in the supplied documentation.

Do I need a connector to integrate HubSpot Marketing Hub with Martini?

No. A dedicated HubSpot connector is not required. Martini can integrate using HubSpot’s confirmed native mechanisms, including REST APIs, selected webhooks, batch or import APIs, the Files API, OAuth 2.0, and private app access tokens.

Is there any extra Lonti cost to integrate HubSpot Marketing Hub with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate HubSpot Marketing 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 based on subscription, usage, and deployment model.

Which HubSpot integration methods should a new implementation use?

Use HubSpot’s versioned REST APIs as the primary integration surface. Use OAuth 2.0 for multi-account or consent-based applications and private app tokens for controlled server-to-server connections. Batch, import, search, and Files APIs can support specific workloads, while GraphQL is limited primarily to selected CMS and content use cases.

Can Martini receive HubSpot webhook events?

Yes, Martini can expose an HTTPS API endpoint or consume supported HubSpot webhook events in a workflow. HubSpot webhook coverage is selective rather than universal, so the required object and event must be verified. Important synchronizations should also use scheduled reconciliation.

How does Martini synchronize HubSpot data incrementally and handle mapping?

A typical workflow uses supported webhook events or HubSpot search with modification timestamps such as createdate and lastmodifieddate, then follows pagination and retrieves associations. Martini maps standard and custom properties into a canonical model, applies validation and consent rules, and performs idempotent target-system writes.

How are HubSpot errors, retries, duplicates, and API limits handled?

Martini workflows can distinguish authentication, permission, validation, rate-limit, and server failures; apply bounded retries with backoff for recoverable responses; and record correlation data for diagnosis. Duplicate prevention uses HubSpot IDs, email addresses, external IDs, or deterministic event keys. Batch and import workflows should inspect item-level errors rather than relying only on HTTP success.

Related Martini documentation

API Integration

Events

Data Processing

Security

Operations

Connect HubSpot Marketing Hub with Martini

Use Martini to build maintainable HubSpot Marketing Hub integrations across REST APIs, selected webhooks, batch imports, files, enterprise applications, and data platforms.

EXPLORE MARTINI
BOOK A DEMO