n8n-nodes-hubspot-advanced

Advanced HubSpot nodes for n8n with intelligent rate limiting, batch operations, association hydration, file management, and list operations.

Features

• ✅ Intelligent Rate Limiting – Respects HubSpot API limits with adaptive throttling
• ✅ Batch Operations – Efficient bulk reads and association hydration using HubSpot's batch APIs
• ✅ Association Hydration – Fetch full associated objects in a single workflow step with batch support
• ✅ Multi-API Version Support – v1, v3, v3-legacy, and v4 endpoints
• ✅ Type-Safe – Full TypeScript implementation with improved type safety (74% reduction in any types)
• ✅ Modular Architecture – Clean separation of concerns with dedicated field descriptions and operations
• ✅ Test-Driven – Comprehensive test coverage
• ✅ File Management – Upload, replace, update properties, and search files in HubSpot File Manager
• ✅ List Operations – Retrieve list members efficiently
• ✅ Marketing Events – Create, manage, and track marketing events with participant registration
• ✅ Dynamic Property Loading – Enhanced property selection with real-time options

Installation

Community Nodes (Recommended)

1. Open n8n
2. Go to Settings → Community Nodes
3. Search for n8n-nodes-hubspot-advanced
4. Click Install

Manual Installation

npm install n8n-nodes-hubspot-advanced

For self-hosted n8n, add to your package.json and rebuild.

Nodes

1. HubSpot CRM

Advanced CRM operations with search, filtering, and batch support.

Operations:

• Get single object
• Get many objects (batch)
• Search with filters and sorting
• Create object
• Update object
• Delete object

Key Features:

• Custom property selection
• Advanced filtering (EQ, NEQ, LT, GT, CONTAINS, etc.)
• Sorting by any property
• Auto-pagination for large result sets

Example Workflow:

[HubSpot CRM]
  Operation: Search
  Object Type: Contacts
  Filters: email CONTAINS "@acme.com"
  Properties: firstname,lastname,email,company
  Sort: createdate DESC
  Limit: 100

2. HubSpot Associations

Read and enrich object associations with optional hydration and batch operations.

Operations:

• Get Associations (IDs only)
• Hydrate Associations (full objects) ⭐
• Batch Get Associations (bulk ID retrieval) ⭐ NEW
• Batch Hydrate Associations (bulk full objects) ⭐ NEW
• Create Association
• Delete Association

Key Features:

• Efficient batch processing for multiple source objects
• Automatic chunking and pagination
• Full object hydration with custom property selection
• Support for all HubSpot object types including custom objects

Batch Hydrate Example:

[HubSpot CRM: Search Contacts] → 500 contacts
        ↓
[HubSpot Associations: Batch Hydrate]
  From: contacts
  To: companies
  Properties: name,domain,industry
        ↓
Output: 500 contacts with full company objects embedded
API Calls: ~4 (instead of 500!)

3. HubSpot Forms

Work with HubSpot forms and submissions with advanced field mapping and GDPR compliance.

Operations:

• Get Forms (v3)
• Get Submissions (v1 API)
• Submit Form (v3-legacy) ⭐

Key Features:

• Multi-object field support (contacts, companies, deals, custom objects)
• GDPR consent and subscription management
• Secure and unsecure endpoint options
• Context tracking (page URI, HUTK, IP address)
• Dynamic subscription type loading
• Dedicated API handler (doesn't impact rate limits of other nodes)

Submit Form Example:

[HubSpot Forms: Submit Form]
  Form: Contact Form
  Email: [email protected]
  Additional Fields:
    - Contact: firstname = John
    - Contact: lastname = Doe
    - Company: name = Acme Corp
  Consent & Subscriptions:
    - Marketing Emails: ✓ Opted In
    - Newsletter: ✓ Opted In
  Endpoint: Secure (recommended)

4. HubSpot Object Schema

Retrieve metadata about object types and properties.

Operations:

• Get Object Types
• Get Properties for an object type

5. HubSpot Files

Work with HubSpot File Manager for uploading, replacing, updating, and searching files.

Operations:

• Upload File
• Replace File
• Update Properties (name, access, parent folder) ⭐
• Search Files
• Import from URL
• Get File
• Delete File

Key Features:

• Multipart form-data support for uploads
• File metadata updates without re-uploading
• Folder path and extension filtering for searches
• Dynamic property selection
• Async URL import support

6. HubSpot Lists

Retrieve members of HubSpot lists.

Operations:

• Get List Members

Key Features:

• Batch retrieval for large lists
• Efficient association handling

7. HubSpot Marketing Events

Create and manage marketing events with participant tracking.

Event Operations:

• Get single event
• Create or Update event (upsert)
• Search/list all events
• Update event
• Delete event
• Get participants with filtering
• Get participation statistics

Contact Operations:

• Register contacts for events
• Mark contacts as attended
• Cancel contact registration

Key Features:

• Support for both contact ID and email identification
• Custom property management
• Participant state filtering (registered, attended, cancelled)
• Automatic pagination for large participant lists
• Dynamic property loading from HubSpot schema

Example Workflow:

[HubSpot Marketing Events: Create]
  Event Name: Product Launch Webinar 2024
  Event Organizer: Marketing Team
  External Event ID: webinar-2024-q1
  Start Date: 2024-03-15T14:00:00Z
  Event Type: WEBINAR
        ↓
[HubSpot Marketing Events: Register]
  Event: Product Launch Webinar 2024
  Identifier Type: Email
  Email: [email protected]
        ↓
[HubSpot Marketing Events: Get Participants]
  Filter: State = REGISTERED

Rate Limiting

Adaptive, response-based rate limiting – works reliably even in n8n Queue Mode with multiple workers.

How it works:

1. No pre-counting – doesn't track requests locally (unreliable in multi-worker setups)
2. Response-header-based – reads X-HubSpot-RateLimit-* headers from every response
3. Adaptive throttling – automatically slows down when Remaining gets low
4. 429 handling – exponential backoff + jitter + Retry-After header support
5. Global coordination – all nodes in the same worker process share pause state via globalThis singleton
6. Concurrent-safe – when 11 requests hit simultaneously, they queue up cleanly

What happens when you hit limits:

Request 1-10: ✅ Success (remaining: 90)
Request 11:   ❌ 429 Rate Limited
  → All nodes pause for 10s (exponential backoff)
  → Retry automatically (up to 5 attempts)
  → Success on retry

No configuration needed – the limiter adapts automatically to your HubSpot tier.

Authentication

Uses existing n8n HubSpot credentials:

1. App Token (recommended for private apps)

   • Create a private app in HubSpot
   • Copy the access token
   • Add as credential in n8n

2. OAuth2 (for public apps)

   • Configure OAuth app in HubSpot
   • Use n8n's OAuth2 flow

Development

Setup

git clone https://github.com/yourusername/n8n-nodes-hubspot-advanced.git
cd n8n-nodes-hubspot-advanced
npm install

Scripts

npm run dev              # Watch mode (TypeScript)
npm run build            # Build for production
npm test                 # Run tests
npm run test:watch       # Test watch mode
npm run test:coverage    # Coverage report
npm run lint             # Lint code
npm run lint:fix         # Fix linting issues

Lokales Testen in n8n

Quick Start:

# 1. Package bauen und verlinken
npm run build
npm link

# 2. In n8n verlinken
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm init -y
npm link n8n-nodes-hubspot-advanced

# 3. n8n starten
n8n start

Bei Änderungen:

# Rebuild
npm run build

# n8n neu starten (Strg+C, dann:)
n8n start

Detaillierte Anleitung: Siehe .windsurf/workflows/local-testing.md

Testing Rate Limiter

Um das Rate Limiting zu testen:

1. Erstelle einen Workflow mit 11+ parallelen HubSpot-Requests
2. Verwende einen Free-Tier HubSpot Account (100 req/10s)
3. Beobachte die Logs für Backoff-Meldungen
4. Erwartetes Verhalten:
   • Requests 1-10: Sofort durchgelassen
   • Request 11+: Pause → Retry → Erfolg

Project Structure

src/
├── nodes/
│   ├── HubSpotCrm/              # Main CRM node
│   ├── HubSpotAssociations/     # Associations with hydration
│   ├── HubSpotForms/            # Forms API
│   ├── HubSpotObjectSchema/     # Schema metadata
│   ├── HubSpotFiles/            # File Manager operations
│   ├── HubSpotLists/            # List member retrieval
│   └── HubSpotMarketingEvents/  # Marketing events and participants
├── transport/
│   ├── RateLimiter.ts           # Adaptive rate limiting
│   └── HubSpotApiRequest.ts     # API wrapper
└── types.ts                     # Shared TypeScript types

tests/
├── unit/                        # Unit tests
├── integration/                 # Integration tests
└── fixtures/                    # Test data

API Version Support

| Feature | API Version | Node | |---|---|---| | CRM Objects (CRUD) | v3 | HubSpot CRM | | Search | v3 | HubSpot CRM | | Associations | v4 | HubSpot Associations | | Batch Read | v3 | All nodes | | Forms List | v3 | HubSpot Forms | | Form Submissions | v1 (legacy) | HubSpot Forms | | Submit Form | v3-legacy (api.hsforms.com) | HubSpot Forms | | Object Schema | v3 | HubSpot Object Schema | | File Upload | v3 | HubSpot Files | | File Replace | v3 | HubSpot Files | | File Search | v3 | HubSpot Files | | List Members | v3 | HubSpot Lists | | Marketing Events (CRUD) | v3 | HubSpot Marketing Events | | Event Participants | v3 | HubSpot Marketing Events | | Contact Registration | v3 | HubSpot Marketing Events |

Roadmap

• [x] Response-based Rate Limiting mit globalThis-Singleton
• [x] 429-Handling mit Exponential Backoff + Jitter
• [x] Retry-After Header Support
• [x] Comprehensive Test Suite (23 Tests)
• [x] Forms API v3 with multi-object support
• [x] GDPR consent and subscription management
• [x] Dedicated form submission handler (rate-limit isolated)
• [x] Custom object support (in Forms and CRM)
• [x] Batch association operations (Get & Hydrate)
• [x] TypeScript type safety improvements (74% reduction in any types)
• [x] Modular architecture with separated field descriptions
• [x] File property updates without re-upload
• [ ] OAuth2 support
• [ ] Webhook triggers
• [ ] Association labels
• [ ] Advanced filtering UI
• [ ] Workflow enrollment
• [ ] Property history retrieval

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure tests pass (pnpm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT

Support

• GitHub Issues
• n8n Community
• HubSpot API Docs

Credits

Built with ❤️ for the n8n community.

Note: This is a community node. It is not officially maintained by n8n or HubSpot.