.png)
Integrate HubSpot with Martini
Martini can integrate HubSpot with enterprise systems by consuming HubSpot REST APIs, receiving selected HubSpot webhook notifications, and orchestrating scheduled workflows for reconciliation and synchronization. It can retrieve and update Contacts, Companies, Deals, Tickets, Products, Custom objects, associations, and related CRM resources, then transform HubSpot JSON payloads into canonical models for databases, queues, files, ERP, billing, service desk, or other APIs. Martini can also call HubSpot batch and import APIs for larger data exchanges and expose REST services that provide an internal façade over HubSpot operations. Managed secrets, pagination, retries, idempotency, monitoring, and configurable business rules support reliable production integrations.
HubSpot integration options at a glance
| Integration point | Supported by HubSpot? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST API | Yes | HubSpot provides REST APIs for CRM objects, associations, schemas, imports, exports, search, and product areas including marketing, sales, service, and CMS. These APIs support retrieving, creating, updating, archiving, searching, and relating supported HubSpot objects. | Martini can consume HubSpot REST APIs directly over HTTP, using generated or reusable services, managed authentication, pagination, field mapping, routing, and error handling. It can also expose REST services that wrap selected HubSpot operations for internal consumers. |
| SOAP API | No | Current HubSpot integrations primarily use REST APIs, webhooks, OAuth, and related HTTP services rather than SOAP. SOAP is not the normal HubSpot integration mechanism described in the research. | Martini should use HubSpot REST APIs or webhook requests for this integration. Martini can work with SOAP-based enterprise systems on the other side of the workflow when a target system requires SOAP. |
| Webhooks | Limited | HubSpot webhooks provide notifications for selected subscription types, including object creation, deletion, property changes, and some association events. They are not a universal stream for every HubSpot event or every object change. | Martini can expose a REST endpoint to receive HubSpot webhook requests and move longer processing into an asynchronous workflow. For unsupported or missed changes, Martini can combine webhook handling with scheduled searches or reconciliation workflows. |
| Events / triggers | Limited | HubSpot supports selected webhook subscription events rather than a universal change-data-capture feed. Incremental synchronization can also use properties such as hs_lastmodifieddate and filtered CRM searches. | Martini can start workflows from inbound webhook requests or scheduled triggers. It can validate event data, deduplicate deliveries, retrieve the current HubSpot object, and route unsupported change types to polling or reconciliation logic. |
| Bulk API / batch export | Limited | Many HubSpot CRM object APIs provide batch read, create, update, and archive operations, with availability and limits varying by object and endpoint. HubSpot also supports imports and selected export capabilities subject to account, resource, permission, and file constraints. | Martini can orchestrate batch endpoints and HubSpot import APIs for migrations, periodic reconciliation, and high-volume loads. It can split work into controlled batches, transform files or payloads, checkpoint progress, and retry failed units. |
| Database access | No | The research does not describe direct database access to HubSpot. HubSpot data should be obtained through its REST APIs, batch or import processes, supported exports, and selected webhook notifications. | Martini can write HubSpot data to SQL databases or other supported data stores after retrieving it through the API. It can preserve HubSpot IDs, checkpoints, associations, and processing status for downstream synchronization. |
| File import/export | Limited | HubSpot supports CRM imports and selected export workflows, but file exchange is not a general replacement for REST APIs and webhooks. File constraints, permissions, and resource availability vary by workflow. | Martini can prepare, transform, and route CSV or other supported file payloads for HubSpot import-oriented workflows, and process supported exports for downstream systems. It can combine file exchange with validation, batching, and database loading. |
| Authentication | Yes | HubSpot supports OAuth 2.0 for public and multi-account integrations and private app access tokens for controlled, single-account server-to-server integrations. Access is limited by scopes, account permissions, and sometimes subscription tier; legacy API keys are deprecated. | Martini can store HubSpot credentials as managed secrets and send OAuth or private app bearer tokens in the HTTP Authorization header. OAuth refresh handling and scope-aware service configuration can be incorporated into the integration design. |
How HubSpot exposes data and business events
HubSpot REST APIs
HubSpot provides REST APIs across CRM objects, associations, schemas, search, imports, exports, and other product areas. List endpoints commonly use cursor-based pagination, while search APIs support filters, property selection, sorting, and pagination for supported CRM objects.
How This works in Martini
How this works in Martini: a scheduled or API-triggered workflow calls the required HubSpot endpoint with a managed bearer token, advances the after cursor, maps the JSON response, and writes the result to an enterprise target. The workflow can retrieve associations separately and persist synchronization checkpoints.
Example Martini workflow
HubSpot Webhooks
HubSpot webhooks support selected subscription types such as object creation, deletion, property changes, and some association events. Coverage is partial, so integrations must verify that the required object and event are available before relying on real-time processing.
How This works in Martini
How this works in Martini: Martini exposes a REST endpoint for HubSpot webhook requests, validates and records the incoming event, responds promptly, and invokes asynchronous processing. The workflow deduplicates the event, retrieves the current object when necessary, and sends unsupported or missed changes to scheduled reconciliation.
Example Martini workflow
HubSpot Batch and Imports
HubSpot supports batch read, create, update, and archive operations for many CRM resources, while its import APIs support CRM data loads including multi-object imports. Availability, limits, file constraints, and permissions vary by object and account.
How This works in Martini
How this works in Martini: Martini partitions source data into controlled batches or prepares import payloads, transforms properties and associations, calls the applicable HubSpot API, checkpoints successful units, and routes failures for bounded retry or review.
Example Martini workflow
Common HubSpot integration patterns
Pattern 1
When to use this pattern
Use this pattern to synchronize HubSpot Contacts and Companies with an ERP or customer database on a schedule. It is appropriate when webhook coverage is incomplete or when a controlled reconciliation process is required.
Data Flow
Example Mapping
| HubSpot Field | Canonical Field | Target Field |
|---|---|---|
| id | externalCustomerId | hubspot_customer_id |
| firstname and lastname | customerName | customer_name |
| emailAddress | ||
| hs_lastmodifieddate | sourceModifiedAt | source_modified_at |
Martini Implementation
Martini invokes paginated HubSpot list or search APIs, selecting only required properties and using an overlap window around the stored hs_lastmodifieddate checkpoint. It maps and validates each object, upserts by a stable HubSpot ID, preserves archival state, and processes associations separately. Rate-limit responses and transient failures use bounded retries, while malformed data is routed to an error path.
Martini features used:
- REST API services
- Scheduler trigger
- Data mapper
- Database services
- Checkpointing
- Error handling
Pattern 2
When to use this pattern
Use this pattern when a HubSpot Deal reaching a defined pipeline stage should create an order, provisioning request, or billing transaction. It combines event-driven processing with a scheduled fallback for changes not covered by HubSpot webhooks.
Data Flow
Example Mapping
| HubSpot Field | Canonical Field | Target Field |
|---|---|---|
| dealname | orderReference | customer_reference |
| amount | orderTotal | order_amount |
| dealstage | salesStage | processing_stage |
| associated company ID | accountId | customer_id |
Martini Implementation
Martini receives a supported HubSpot webhook or identifies the Deal through an incremental search, then retrieves the Deal and associated Contact or Company. Business rules verify the required stage, amount, and customer identity before submitting the downstream request. An idempotency key prevents duplicate orders, and the resulting external ID or failure status can be written back to the HubSpot Deal.
Martini features used:
- Webhook endpoint
- Scheduled reconciliation
- Association retrieval
- Business rules
- Idempotency
- Retry and error queue
Pattern 3
When to use this pattern
Use this pattern to synchronize HubSpot Tickets with an external service desk or internal case-management system. A reverse flow can return external status and resolution details to HubSpot.
Data Flow
Example Mapping
| HubSpot Field | Canonical Field | Target Field |
|---|---|---|
| subject | caseSummary | title |
| hs_ticket_priority | priority | priority |
| hs_pipeline_stage | caseStatus | status |
| associated contact ID | customerId | requester_id |
Martini Implementation
Martini reads new or modified Tickets through supported searches or webhook notifications, retrieves required associations, and maps HubSpot pipeline values to service-desk statuses. It creates or updates the external case using the HubSpot Ticket ID as a correlation key. Reverse updates are validated to avoid loops, and failed calls are retried without duplicating cases.
Martini features used:
- REST API services
- Webhook handling
- Field mapping
- Conditional routing
- Correlation IDs
- Monitoring and retry
Pattern 4
When to use this pattern
Use this pattern for an initial migration, periodic reconciliation, or large data exchange involving Contacts, Companies, Deals, Products, or Custom objects. Batch and import APIs are preferable to one request per object for high-volume workloads.
Data Flow
Example Mapping
| HubSpot Field | Canonical Field | Target Field |
|---|---|---|
| customer_number | externalCustomerId | external_customer_id |
| account_name | companyName | name |
| service_code | productCode | hs_sku |
| updated_at | sourceModifiedAt | source_modified_at |
Martini Implementation
Martini reads source files or database pages, validates required properties, transforms values and associations, and partitions the result into HubSpot-compatible batch or import payloads. It records batch identifiers and outcomes, retries only failed units within policy, and produces an audit result for rejected rows or schema mismatches.
Martini features used:
- File and database services
- Batch orchestration
- JSON transformation
- Data validation
- Checkpointing
- Operational monitoring
How to build a HubSpot integration in Martini
Objective
Establish a controlled connection to HubSpot using OAuth 2.0 for multi-account installations or a private app access token for a controlled single-account integration.
Instructions in Martini
- Create the required HubSpot app or private app and grant only necessary CRM and product scopes.
- Store the bearer token, client credentials, and refresh information as Martini managed secrets.
- Configure the HubSpot HTTP service with the Authorization header and environment-specific endpoint settings.
Objective
Select the execution model that matches HubSpot coverage and business latency requirements: inbound webhook processing for selected events, scheduled polling, API invocation, or batch execution.
Instructions in Martini
- Verify that the required HubSpot webhook subscription type exists before designing a real-time flow.
- Use a scheduler and hs_lastmodifieddate search checkpoint for incremental or reconciliation workflows.
- Persist cursors, checkpoints, and batch state outside transient workflow data.
Objective
Convert HubSpot JSON properties, associations, dates, enumerations, and custom schemas into a canonical internal model or target-specific payload.
Instructions in Martini
- Select only required HubSpot properties and retrieve associations explicitly when needed.
- Normalize timestamps, numeric values, enumerations, and multi-select properties.
- Make custom object and property mappings configurable where account schemas vary.
Objective
Enforce lifecycle, pipeline, ownership, validation, and duplicate-prevention rules before data is written to a target or sent back to HubSpot.
Instructions in Martini
- Check required fields and permitted Deal or Ticket stages before creating downstream transactions.
- Use HubSpot object IDs, event identifiers, or stable external IDs for idempotency.
- Route unsupported events, missing associations, and schema mismatches to deliberate exception paths.
Objective
Create or update the ERP, service desk, database, file, queue, or other API target and optionally update HubSpot with external identifiers or processing results.
Instructions in Martini
- Use upsert or correlation-key logic supported by the target system.
- For large loads, partition work and call HubSpot batch or import APIs where applicable.
- Avoid assuming repeated POST operations are safe unless the target explicitly supports idempotency.
Objective
Operate the integration with visibility into rate limits, failed requests, rejected rows, webhook duplicates, and synchronization progress.
Instructions in Martini
- Handle HTTP 429 responses and honor Retry-After when supplied.
- Use bounded exponential backoff for transient failures and preserve failed payloads for replay.
- Monitor workflow logs, checkpoints, batch results, and reconciliation counts.
Common HubSpot data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Contacts | Synchronize people, lifecycle information, communication details, and customer attributes between HubSpot and an ERP, customer database, data warehouse, or customer platform. | ERP, SQL database, data warehouse, customer service platform, marketing platform | Martini retrieves selected properties through paginated or search APIs, normalizes values, preserves the HubSpot object ID, and applies create-or-update rules with checkpointing and deduplication. |
| Companies | Synchronize organizations or accounts and use them as the business context for customer, sales, and service workflows. | ERP, account database, data warehouse, service desk, billing platform | Martini maps company properties to a canonical account model and separately retrieves or processes associations to Contacts, Deals, and Tickets when relationship data is required. |
| Deals | Trigger order, provisioning, billing, revenue, or sales operations when an opportunity reaches a defined lifecycle or pipeline stage. | ERP, billing platform, order management, fulfillment system, data warehouse | Martini reads the Deal and relevant associations, applies stage and status rules, submits a downstream request, and writes an external order or processing identifier back to HubSpot where appropriate. |
| Tickets | Synchronize customer support cases, status, priority, ownership, category, and resolution information with an external service desk or case-management system. | Service desk, case-management system, customer database, data warehouse | Martini maps ticket properties and customer associations in both directions, applies status translation rules, and uses idempotent updates to prevent duplicate cases or updates. |
| Products | Exchange items or services maintained in the HubSpot product library with ERP, catalog, billing, or order systems. | ERP, product catalog, billing platform, order management | Martini retrieves required product properties, converts numeric and date values explicitly, validates required fields, and routes rejected items to error handling without stopping unrelated records. |
| Custom objects | Synchronize account-defined CRM data that does not fit standard Contacts, Companies, Deals, Tickets, or Products, including associated business-specific structures. | SQL database, data warehouse, ERP, internal applications | Martini can inspect current schemas, map configurable properties, preserve custom object IDs and association types, and handle unknown or changed properties through deliberate validation and exception rules. |
Authentication and security considerations
Use scoped HubSpot credentials
HubSpot supports OAuth 2.0 for multi-account applications and private app access tokens for controlled single-account integrations. Legacy API keys are deprecated and should not be used for new integrations.
- Store tokens, client credentials, and refresh information as Martini managed secrets.
- Send OAuth or private app tokens as Bearer credentials in the HTTP Authorization header.
- Request only the CRM object and product scopes required by each workflow.
- Account permissions and subscription tiers may restrict access even when a token is valid.
Operational considerations for HubSpot integrations
Design for HubSpot API behavior
- Handle HTTP 429 responses, honor Retry-After when supplied, and use bounded exponential backoff.
- Persist cursor-based after values and synchronization checkpoints rather than relying on page numbers.
- Deduplicate webhook deliveries and retries using event identifiers, object IDs, or stable external IDs.
- Use scheduled reconciliation for changes outside selected HubSpot webhook coverage.
- Inspect schemas and make mappings configurable for custom properties, custom objects, pipelines, and association labels.
- Normalize dates, timestamps, enumerations, numeric values, and multi-select properties explicitly.
- Test pagination, association retrieval, archive handling, rate-limit responses, schema changes, and partial batch failures before production deployment.
Why use Martini instead of scripts or point-to-point integrations?
Build maintainable integration services
Scripts and point-to-point connections often combine authentication, mapping, retries, checkpoints, and monitoring in code that is difficult to reuse. Martini provides a structured integration platform for consuming HubSpot API definitions and webhook requests, transforming payloads, orchestrating workflows, and exposing reusable REST services.
- Centralize mappings and business rules instead of duplicating them across scripts.
- Combine real-time webhook handling with scheduled polling and reconciliation.
- Connect HubSpot data to databases, files, queues, and enterprise APIs through one workflow model.
- Use managed secrets, error handling, monitoring, and deployment practices to support production operations.
- Extend transformations with custom JVM-compatible logic when standard mapping is insufficient.
Frequently asked questions
No native HubSpot connector is documented in the supplied Martini context. Martini can consume HubSpot REST APIs, receive selected HubSpot webhook notifications through a REST endpoint, orchestrate scheduled searches, and transform data for databases, files, queues, ERP, billing, service desk, and other APIs.
Use OAuth 2.0 when the integration is installed across multiple HubSpot accounts or requires user authorization. A private app access token is generally more appropriate for a controlled, single-account server-to-server integration. In both cases, scopes and account permissions limit access.
Yes. Martini can expose a REST endpoint for HubSpot webhook requests and process them asynchronously. HubSpot webhook coverage is limited to selected subscription types, so scheduled polling or reconciliation should cover unsupported or missed changes.
Yes. Martini can combine supported webhook events with HubSpot searches filtered by hs_lastmodifieddate and a persisted checkpoint. An overlap window and object-ID deduplication reduce the risk of missing updates while a synchronization is running.
HubSpot uses associations to connect Deals with Contacts, Companies, Tickets, and other supported objects. Martini should retrieve or request the required associations, preserve HubSpot IDs and association types, and apply relationship mappings explicitly.
For supported CRM resources, Martini can call HubSpot batch read, create, update, and archive endpoints. It can also orchestrate HubSpot import APIs for larger or file-oriented loads, subject to the specific object's availability, limits, permissions, and import constraints.
The workflow should store an idempotency record keyed by the HubSpot event or object/change identity. Before creating a downstream record, Martini checks that key and either skips the duplicate or applies a safe update.
This page is an integration briefing covering HubSpot APIs, selected webhooks, authentication, data objects, batch and import workflows, implementation patterns, and operational controls for connecting HubSpot with enterprise systems through Martini.
Related Martini documentation
Workflows
Connect HubSpot to your enterprise systems
Use Martini to build governed HubSpot integrations that combine APIs, selected webhook events, scheduled synchronization, transformation, and operational monitoring.