n8n-nodes-hubspot-guard

Community node that calls the HubSpot API safely by throttling requests to stay under the 10-second rolling limit and retrying 429 responses with a wait (defaults to 60 seconds fallback).

Why this exists

If you hit an n8n webhook 5 times, you can end up with 5 workflow executions calling HubSpot at the same time. HubSpot enforces a rolling 10-second burst limit and returns 429 when exceeded. This node coordinates requests across concurrent executions (within one n8n process) using a shared limiter.

HubSpot documents the 10-second rolling limit and rate-limit headers here: https://developers.hubspot.com/docs/api/usage-details.

Publish this package

Option 1: Publish to npm (public)

1. Create an account at npmjs.com if you don’t have one.
2. (Recommended) Use a scoped name so the name isn’t taken. In package.json set:
   • "name": "@YOUR_NPM_USERNAME/n8n-nodes-hubspot-guard"
   • Example: @jane/n8n-nodes-hubspot-guard
3. Log in and publish:

   npm login
   npm run build
   npm publish

   For a scoped package that should be public:

   npm publish --access public

4. In n8n: Settings → Community Nodes → Install and enter the package name (e.g. @jane/n8n-nodes-hubspot-guard).

Option 2: Publish to a private registry

• Point npm at your registry (e.g. set registry in .npmrc or use npm config set registry https://your-registry.example.com).
• Run npm login (if required) and npm publish. Then install the same package name from that registry in n8n (if n8n is configured to use it).

Option 3: Use without publishing (local tarball)

1. In this project folder:

   npm run build
   npm pack

   This creates a file like n8n-nodes-hubspot-guard-0.1.0.tgz.
2. In n8n Settings → Community Nodes → Install, choose “Install from a file” (or similar) and select that .tgz file.
   • Or from the machine where n8n runs: npm install /path/to/n8n-nodes-hubspot-guard-0.1.0.tgz in n8n’s custom nodes directory, depending on your setup.

Install

Install into n8n (Community Nodes UI)

1. Publish this package to a registry (private npm is fine), or use the tarball method above; then install it via Settings → Community Nodes in n8n.

Local dev install (Custom extensions)

If you run n8n yourself, you can load this node as a custom extension:

1. Build this package:
   • npm install
   • npm run build
2. Point n8n at the folder (examples):
   • Set N8N_CUSTOM_EXTENSIONS to the absolute path of this project folder, or
   • Copy the dist/ folder into your configured custom extensions directory.

Restart n8n, then search for the node HubSpot Guard.

Usage

1. Create credentials: HubSpot Private App (Guarded) and paste your private app token.
2. Add the node HubSpot Guard and configure:
   • Method and Path (e.g. /crm/v3/objects/contacts)
   • burstLimit (default 110 per 10 seconds; adjust for your app type/tier)
   • fallbackWaitMs (default 60000 ms = 1 minute)

Quick test (reproduces your “5 webhooks at once” case)

• Create a workflow with:
  • Webhook Trigger
  • HubSpot Guard (calls any lightweight endpoint, like listing a small page of contacts)
• Trigger the webhook 5+ times quickly. You should see:
  • Calls are queued, not all executed at once
  • If HubSpot returns 429, the node waits (Retry-After / headers / fallback 60s) then retries

The node returns:

• statusCode
• body
• headers (optional)
• retries and total waitedMs

Notes / limitations

• The limiter is in-memory per n8n process. If you run multiple n8n instances/workers, you’ll want a Redis-backed shared limiter (Bottleneck supports clustering).
• HubSpot Search endpoints may not include rate-limit headers; in that case the node uses Retry-After or the fallback wait.