HubSpot Load & Scale

Overview

Load testing and capacity planning for HubSpot integrations, constrained by the 10 requests/second and 500,000 requests/day API limits.

Prerequisites

• k6 or similar load testing tool
• HubSpot developer test account (never load test against production)
• Understanding of HubSpot rate limits

Instructions

Step 1: Understand HubSpot Rate Limit Constraints

Your integration's maximum throughput is bound by HubSpot's limits:

Effective throughput with batching:

• Individual operations: 10 records/sec
• Batch operations: 1,000 records/sec (10 batches/sec x 100 records/batch)

Step 2: k6 Load Test Script

// hubspot-load-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';
import { Rate, Trend } from 'k6/metrics';

const errorRate = new Rate('hubspot_errors');
const rateLimited = new Rate('hubspot_rate_limited');

export const options = {
  stages: [
    { duration: '1m', target: 2 },    // warm up (2 req/sec)
    { duration: '3m', target: 5 },    // moderate load
    { duration: '2m', target: 8 },    // approach limit
    { duration: '2m', target: 10 },   // at limit
    { duration: '1m', target: 0 },    // ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<2000'],       // 95% under 2s
    hubspot_errors: ['rate<0.05'],           // <5% errors
    hubspot_rate_limited: ['rate<0.10'],     // <10% rate limited
  },
};

const BASE_URL = 'https://api.hubapi.com';
const TOKEN = __ENV.HUBSPOT_ACCESS_TOKEN;

export default function () {
  // Test: List contacts (GET)
  const listRes = http.get(
    `${BASE_URL}/crm/v3/objects/contacts?limit=10&properties=email,firstname`,
    { headers: { Authorization: `Bearer ${TOKEN}` } }
  );

  check(listRes, { 'list contacts: 200': (r) => r.status === 200 });
  errorRate.add(listRes.status >= 400 && listRes.status !== 429);
  rateLimited.add(listRes.status === 429);

  sleep(0.1); // 100ms between requests per VU

  // Test: Search contacts (POST)
  const searchRes = http.post(
    `${BASE_URL}/crm/v3/objects/contacts/search`,
    JSON.stringify({
      filterGroups: [{
        filters: [{
          propertyName: 'lif

HubSpot Local Dev Loop

Overview

Set up a fast local development workflow for HubSpot integrations with sandbox accounts, mocking, and test utilities.

Prerequisites

• Completed hubspot-install-auth setup
• Node.js 18+ with npm/pnpm
• HubSpot developer test account (free at developers.hubspot.com)

Instructions

Step 1: Create Project Structure

my-hubspot-project/
├── src/
│   ├── hubspot/
│   │   ├── client.ts       # Singleton @hubspot/api-client wrapper
│   │   ├── contacts.ts     # Contact operations
│   │   ├── deals.ts        # Deal operations
│   │   └── types.ts        # HubSpot type definitions
│   └── index.ts
├── tests/
│   ├── mocks/
│   │   └── hubspot.ts      # Shared mock factory
│   ├── contacts.test.ts
│   └── deals.test.ts
├── .env.local               # Local secrets (git-ignored)
├── .env.example             # Template for team
├── tsconfig.json
└── package.json

Step 2: Create Client Singleton

// src/hubspot/client.ts
import * as hubspot from '@hubspot/api-client';

let instance: hubspot.Client | null = null;

export function getHubSpotClient(): hubspot.Client {
  if (!instance) {
    if (!process.env.HUBSPOT_ACCESS_TOKEN) {
      throw new Error('HUBSPOT_ACCESS_TOKEN environment variable is required');
    }
    instance = new hubspot.Client({
      accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
      numberOfApiCallRetries: 3,
    });
  }
  return instance;
}

// Reset client (useful for tests)
export function resetHubSpotClient(): void {
  instance = null;
}

Step 3: Configure Testing with Vitest

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "test:integration": "HUBSPOT_TEST=true vitest --config vitest.integration.config.ts"
  },
  "devDependencies": {
    "@hubspot/api-client": "^13.0.0",
    "vitest": "^2.0.0",
    "tsx": "^4.0.0"
  }
}

Step 4: Mock HubSpot API for Unit Tests

// tests/mocks/hubspot.ts
import { vi } from 'vitest';

export function createMockHubSpotClient() {
  return {
    crm: {
      contacts: {
        basicApi: {
          create: vi.fn().mockResolvedValue({
            id: '101',
            properties: { firstname: 'Jane', lastname: 'Doe', email: 'jane@test.com' },
            createdAt: new Date().toISOString(),
            updatedAt: new Date().toISOString(),
            archived: false,
          }),
          getById: vi.fn().mockResolvedValue({
            id: '101',
            properties: { firstname: 'Jane', lastname: 'Doe'

HubSpot Migration Deep Dive

Overview

Comprehensive guide for migrating CRM data into HubSpot, including data mapping, batch imports via API, validation, and rollback procedures.

Prerequisites

• Source CRM data exported (CSV or API access)
• HubSpot account with required scopes
• Custom properties created in HubSpot for non-default fields

Instructions

Step 1: Data Inventory and Mapping

// Map source CRM fields to HubSpot properties
interface FieldMapping {
  sourceField: string;
  hubspotProperty: string;
  transform?: (value: string) => string;
  required: boolean;
}

const contactFieldMap: FieldMapping[] = [
  { sourceField: 'Email', hubspotProperty: 'email', required: true },
  { sourceField: 'First Name', hubspotProperty: 'firstname', required: false },
  { sourceField: 'Last Name', hubspotProperty: 'lastname', required: false },
  { sourceField: 'Phone', hubspotProperty: 'phone', required: false },
  { sourceField: 'Company', hubspotProperty: 'company', required: false },
  {
    sourceField: 'Lead Status',
    hubspotProperty: 'lifecyclestage',
    transform: (val) => {
      // Map source values to HubSpot lifecycle stages
      const map: Record<string, string> = {
        'New': 'lead',
        'Qualified': 'marketingqualifiedlead',
        'Won': 'customer',
      };
      return map[val] || 'lead';
    },
    required: false,
  },
];

function mapRecord(
  source: Record<string, string>,
  fieldMap: FieldMapping[]
): Record<string, string> {
  const mapped: Record<string, string> = {};
  for (const field of fieldMap) {
    const value = source[field.sourceField];
    if (value !== undefined && value !== '') {
      mapped[field.hubspotProperty] = field.transform ? field.transform(value) : value;
    } else if (field.required) {
      throw new Error(`Missing required field: ${field.sourceField}`);
    }
  }
  return mapped;
}

Step 2: Create Custom Properties Before Import

import * as hubspot from '@hubspot/api-client';

const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
});

// Create custom properties that don't exist in HubSpot
async function ensureCustomProperties(objectType: string) {
  const customProps = [
    {
      name: 'source_crm_id',
      label: 'Source CRM ID',
      type: 'string',
      fieldType: 'text',
      groupName: 'contactinformation',
      description: 'Original record ID from source CRM',
    },
    {
      name: 'migration_date',
      label: 'Migration Date',
      type: 'date',
      fieldType: 'date',
      group

HubSpot Multi-Environment Setup

Overview

Configure HubSpot integrations across dev/staging/production using separate HubSpot portals (test accounts), environment-specific tokens, and configuration management.

Prerequisites

• HubSpot developer account (for test portals)
• Secret management solution (Vault, AWS SM, GCP SM)
• CI/CD pipeline with environment variables

Instructions

Step 1: Environment Strategy

Create a free developer test account at developers.hubspot.com.

Step 2: Environment Configuration

// src/config/hubspot.ts
import * as hubspot from '@hubspot/api-client';

type Environment = 'development' | 'staging' | 'production';

interface HubSpotEnvConfig {
  accessToken: string;
  portalId: string;
  retries: number;
  cacheTtlMs: number;
}

const ENV_CONFIG: Record<Environment, Partial<HubSpotEnvConfig>> = {
  development: {
    retries: 1,
    cacheTtlMs: 0, // no cache in dev for fresh data
  },
  staging: {
    retries: 3,
    cacheTtlMs: 60000,
  },
  production: {
    retries: 5,
    cacheTtlMs: 300000,
  },
};

function getEnvironment(): Environment {
  const env = process.env.NODE_ENV || 'development';
  if (['development', 'staging', 'production'].includes(env)) {
    return env as Environment;
  }
  return 'development';
}

export function getHubSpotConfig(): HubSpotEnvConfig {
  const env = getEnvironment();
  return {
    accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
    portalId: process.env.HUBSPOT_PORTAL_ID!,
    ...ENV_CONFIG[env],
  } as HubSpotEnvConfig;
}

export function createHubSpotClient(): hubspot.Client {
  const config = getHubSpotConfig();
  return new hubspot.Client({
    accessToken: config.accessToken,
    numberOfApiCallRetries: config.retries,
  });
}

Step 3: Per-Environment Secrets

# .env.development (git-ignored)
HUBSPOT_ACCESS_TOKEN=pat-na1-test-xxxxx    # developer test account
HUBSPOT_PORTAL_ID=12345678

# .env.staging (git-ignored)
HUBSPOT_ACCESS_TOKEN=pat-na1-staging-xxxxx  # sandbox portal
HUBSPOT_PORTAL_ID=23456789

# .env.production (NEVER in files -- use secret manager)
# Stored in AWS Secrets Manager / GCP Secret Manager / Vault

# AWS Secrets Manag

HubSpot Observability

Overview

Instrument HubSpot API calls with Prometheus metrics, OpenTelemetry tracing, and structured logging to monitor CRM integration health.

Prerequisites

• Prometheus or compatible metrics backend
• OpenTelemetry SDK (optional, for tracing)
• Structured logging library (pino recommended)

Instructions

Step 1: Prometheus Metrics

import { Counter, Histogram, Gauge, Registry } from 'prom-client';

const registry = new Registry();

const hubspotRequests = new Counter({
  name: 'hubspot_api_requests_total',
  help: 'Total HubSpot API requests',
  labelNames: ['method', 'object_type', 'status'],
  registers: [registry],
});

const hubspotLatency = new Histogram({
  name: 'hubspot_api_request_duration_seconds',
  help: 'HubSpot API request duration',
  labelNames: ['method', 'object_type'],
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2, 5],
  registers: [registry],
});

const hubspotRateLimit = new Gauge({
  name: 'hubspot_rate_limit_remaining',
  help: 'HubSpot daily rate limit remaining',
  labelNames: ['type'],
  registers: [registry],
});

const hubspotErrors = new Counter({
  name: 'hubspot_api_errors_total',
  help: 'HubSpot API errors by category',
  labelNames: ['status_code', 'category'],
  registers: [registry],
});

Step 2: Instrumented Client Wrapper

import * as hubspot from '@hubspot/api-client';

class InstrumentedHubSpotClient {
  private client: hubspot.Client;

  constructor() {
    this.client = new hubspot.Client({
      accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
      numberOfApiCallRetries: 3,
    });
  }

  async tracked<T>(
    method: string,
    objectType: string,
    operation: () => Promise<T>
  ): Promise<T> {
    const timer = hubspotLatency.startTimer({ method, object_type: objectType });

    try {
      const result = await operation();
      hubspotRequests.inc({ method, object_type: objectType, status: 'success' });
      return result;
    } catch (error: any) {
      const statusCode = error?.code || error?.statusCode || 500;
      const category = error?.body?.category || 'UNKNOWN';

      hubspotRequests.inc({ method, object_type: objectType, status: 'error' });
      hubspotErrors.inc({ status_code: String(statusCode), category });
      throw error;
    } finally {
      timer();
    }
  }

  // Example: instrumented contact operations
  async getContact(id: string, properties: string[]) {
    return this.tracked('GET', 'contacts', () =>
      this.client.crm.contacts.basicApi.getById(id, properties)
    );
  }

  async createContact(properties: Record<string, string>) {
    return this.tracked('POST'

HubSpot Performance Tuning

Overview

Optimize HubSpot API performance through batch operations, caching, search optimization, and request minimization.

Prerequisites

• @hubspot/api-client installed
• Understanding of your access patterns (read-heavy vs write-heavy)
• Optional: Redis for distributed caching

Instructions

Step 1: Use Batch APIs Everywhere

The single biggest performance win: batch operations reduce API calls by up to 100x.

import * as hubspot from '@hubspot/api-client';

const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  numberOfApiCallRetries: 3,
});

// BAD: 100 API calls for 100 contacts
async function getContactsSlow(ids: string[]) {
  return Promise.all(ids.map(id =>
    client.crm.contacts.basicApi.getById(id, ['email', 'firstname'])
  ));
}

// GOOD: 1 API call for 100 contacts
async function getContactsFast(ids: string[], properties: string[]) {
  // POST /crm/v3/objects/contacts/batch/read
  const result = await client.crm.contacts.batchApi.read({
    inputs: ids.map(id => ({ id })),
    properties,
    propertiesWithHistory: [],
  });
  return result.results;
}

// For more than 100 records, chunk:
async function getContactsChunked(ids: string[], properties: string[]) {
  const results = [];
  for (let i = 0; i < ids.length; i += 100) {
    const chunk = ids.slice(i, i + 100);
    const batch = await getContactsFast(chunk, properties);
    results.push(...batch);
  }
  return results;
}

Step 2: Request Only Needed Properties

// BAD: Returns ALL default properties (slow, large payload)
const contact = await client.crm.contacts.basicApi.getById(id);

// GOOD: Only request what you need (fast, small payload)
const contact = await client.crm.contacts.basicApi.getById(
  id,
  ['email', 'firstname', 'lastname', 'lifecyclestage'] // specific properties
);

Step 3: Cache Frequently Accessed Data

import { LRUCache } from 'lru-cache';

const contactCache = new LRUCache<string, any>({
  max: 5000,              // max entries
  ttl: 5 * 60 * 1000,     // 5 minute TTL
  updateAgeOnGet: true,
});

async function getCachedContact(id: string, properties: string[]) {
  const cacheKey = `contact:${id}`;
  const cached = contactCache.get(cacheKey);
  if (cached) return cached;

  const contact = await client.crm.contacts.basicApi.getById(id, properties);
  contactCache.set(cacheKey, contact);
  return contact;
}

// Invalidate on webhook events
function invalidateContactCache(contactId: string): void {
  contactCache.delete(`contact:${contactId}`);
}

Step 4: Optimize Search Queries

// BAD: Overly broad search, returns too 

HubSpot Policy & Guardrails

Overview

Automated policy enforcement for HubSpot integrations: secret scanning, ESLint rules, CI checks for token leaks, and runtime guardrails.

Prerequisites

• ESLint configured in project
• CI/CD pipeline (GitHub Actions)
• TypeScript for compile-time enforcement

Instructions

Step 1: Secret Scanning (Prevent Token Leaks)

# .github/workflows/hubspot-security.yml
name: HubSpot Security Scan
on: [push, pull_request]

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan for HubSpot private app tokens
        run: |
          # Pattern: pat-{region}{number}-{uuid}
          if grep -rE "pat-[a-z]{2}[0-9]-[a-f0-9-]{36}" \
            --include="*.ts" --include="*.js" --include="*.json" --include="*.yaml" \
            --exclude-dir=node_modules --exclude-dir=.git .; then
            echo "::error::HubSpot private app token found in source code!"
            echo "Rotate this token immediately in HubSpot Settings > Private Apps"
            exit 1
          fi

      - name: Scan for deprecated API keys
        run: |
          # Pattern: hapikey=uuid
          if grep -rE "hapikey=[a-f0-9-]{36}" \
            --include="*.ts" --include="*.js" --include="*.env.example" \
            --exclude-dir=node_modules .; then
            echo "::error::Deprecated HubSpot API key found! Migrate to private app tokens."
            exit 1
          fi

      - name: Verify .gitignore includes .env files
        run: |
          if ! grep -q "^\.env$" .gitignore; then
            echo "::error::.gitignore missing .env entry"
            exit 1
          fi

Step 2: ESLint Rule -- No Deprecated API Key Auth

// eslint-rules/no-hubspot-api-key.js
module.exports = {
  meta: {
    type: 'problem',
    docs: { description: 'Disallow deprecated HubSpot API key authentication' },
    messages: {
      noApiKey: 'HubSpot API keys are deprecated. Use accessToken from a private app instead.',
      useAccessToken: 'Use { accessToken: process.env.HUBSPOT_ACCESS_TOKEN } instead of { apiKey }',
    },
  },
  create(context) {
    return {
      Property(node) {
        if (
          node.key.type === 'Identifier' &&
          node.key.name === 'apiKey' &&
          node.parent?.parent?.callee?.name === 'Client'
        ) {
          context.report({ node, messageId: 'noApiKey' });
        }
      },
      Literal(node) {
        if (typeof node.value === 'string') {
          // Detect hardcoded private app tokens
          if (node.value.match(/^pat-[a-z]{2}\d-[a-f0-9-]{36}$/)) {
            con

HubSpot Production Checklist

Overview

Complete checklist for deploying HubSpot CRM integrations to production with health checks, monitoring, and rollback procedures.

Prerequisites

• Staging environment tested and verified
• Production private app token with minimal scopes
• Deployment pipeline configured
• Monitoring/alerting ready

Instructions

Step 1: Pre-Deployment Verification

• [ ] Production private app created with minimal scopes
• [ ] Access token stored in secret manager (not env file)
• [ ] .env files in .gitignore
• [ ] No hardcoded tokens in source (grep -r "pat-na1" src/)
• [ ] Webhook endpoints use HTTPS only
• [ ] Webhook signature verification implemented (v3)
• [ ] Error handling covers 401, 403, 404, 409, 429, 5xx
• [ ] Rate limiting/backoff implemented (numberOfApiCallRetries: 3)
• [ ] Batch operations used where possible (max 100/batch)
• [ ] All tests passing against developer test account

Step 2: Health Check Endpoint

import * as hubspot from '@hubspot/api-client';

interface HealthCheckResult {
  status: 'healthy' | 'degraded' | 'unhealthy';
  hubspot: {
    connected: boolean;
    latencyMs: number;
    rateLimitRemaining?: number;
  };
  timestamp: string;
}

async function hubspotHealthCheck(): Promise<HealthCheckResult> {
  const client = new hubspot.Client({
    accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  });

  const start = Date.now();
  try {
    // Cheapest possible API call: fetch 1 contact
    await client.crm.contacts.basicApi.getPage(1);
    return {
      status: 'healthy',
      hubspot: {
        connected: true,
        latencyMs: Date.now() - start,
      },
      timestamp: new Date().toISOString(),
    };
  } catch (error: any) {
    const status = error?.code || error?.statusCode || 500;
    return {
      status: status === 429 ? 'degraded' : 'unhealthy',
      hubspot: {
        connected: false,
        latencyMs: Date.now() - start,
      },
      timestamp: new Date().toISOString(),
    };
  }
}

// Express endpoint
app.get('/health', async (req, res) => {
  const result = await hubspotHealthCheck();
  const httpStatus = result.status === 'healthy' ? 200 :
                     result.status === 'degraded' ? 200 : 503;
  res.status(httpStatus).json(result);
});

Step 3: Monitoring Alerts

Critical: Limits are per HubSpot portal (account), not per app. All private apps and OAuth apps in the same portal share the same limit bucket.

Step 2: Use SDK Built-in Retries

import * as hubspot from '@hubspot/api-client';

// The SDK has built-in retry for 429 responses
const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  numberOfApiCallRetries: 3, // retries 429 and 5xx automatically
});

Step 3: Custom Backoff with Retry-After Header

async function withHubSpotBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 30000 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;

      const status = error?.code || error?.statusCode || error?.response?.status;

      // Only retry on 429 and 5xx
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Honor Retry-After header from HubSpot
      let delay: number;
      const retryAfter = error?.response?.headers?.['retry-after'];
      if (retryAfter) {
        delay = parseInt(retryAfter) * 1000;
      } else {
        // Exponential backoff with jitter
        const exponential = config.baseDelayMs * Math.pow(2, attempt);
        const jitter = Math.random() * 500;
        delay = Math.min(exponential + jitter, config.maxDelayMs);
      }

      console.warn(`HubSpot rate limited (attempt ${attempt + 1}/${config.maxRetries}). ` +
        `Retrying in ${delay}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Step 4: Request Queue for Throughput Control

import PQueue from 'p-queue';

// Queue that respects HubSpot's 10 req/sec limit

HubSpot Reference Architecture

Overview

Production-ready layered architecture for HubSpot CRM integrations with typed clients, service abstraction, caching, and webhook handling.

Prerequisites

• TypeScript 5+ project
• @hubspot/api-client v13+ installed
• Understanding of layered architecture patterns

Instructions

Step 1: Project Structure

my-hubspot-integration/
├── src/
│   ├── hubspot/                    # HubSpot infrastructure layer
│   │   ├── client.ts              # Singleton @hubspot/api-client wrapper
│   │   ├── types.ts               # HubSpot-specific types
│   │   ├── errors.ts              # Error classification
│   │   ├── cache.ts               # Response caching
│   │   └── associations.ts        # Association type constants
│   ├── services/                   # Business logic layer
│   │   ├── contact.service.ts     # Contact CRUD + business rules
│   │   ├── deal.service.ts        # Deal pipeline operations
│   │   ├── company.service.ts     # Company management
│   │   └── sync.service.ts        # Data synchronization
│   ├── api/                        # API layer
│   │   ├── routes/
│   │   │   ├── contacts.ts        # REST endpoints
│   │   │   ├── deals.ts
│   │   │   └── webhooks.ts        # Webhook receiver
│   │   └── middleware/
│   │       ├── auth.ts            # Request auth
│   │       └── webhook-verify.ts  # HubSpot signature verification
│   ├── jobs/                       # Background jobs
│   │   ├── sync-contacts.ts       # Scheduled sync
│   │   └── process-webhooks.ts    # Async event processing
│   └── index.ts
├── tests/
│   ├── unit/
│   │   ├── services/
│   │   └── mocks/hubspot.ts       # Shared mock factory
│   └── integration/
│       └── hubspot.integration.test.ts
├── config/
│   ├── default.ts                 # Shared config
│   └── production.ts              # Production overrides
└── package.json

Step 2: Infrastructure Layer

// src/hubspot/client.ts
import * as hubspot from '@hubspot/api-client';

let instance: hubspot.Client | null = null;

export function getHubSpotClient(): hubspot.Client {
  if (!instance) {
    instance = new hubspot.Client({
      accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
      numberOfApiCallRetries: 3,
    });
  }
  return instance;
}

// src/hubspot/associations.ts
// Default association type IDs (HUBSPOT_DEFINED category)
export const ASSOCIATION_TYPES = {
  CONTACT_TO_COMPANY: 1,
  CONTACT_TO_DEAL: 3,
  COMPANY_TO_DEAL: 5,
  CONTACT_TO_TICKET: 16,
  NOTE_TO_CONTACT: 202,
  TASK_TO_CONTACT: 204,
  NOTE_TO_DEAL: 214,
} as const;

// src/hubspot/errors.ts
export class HubSpotError extends Error {
  constructor(
    message: string,
    public readonly statusCode: number,
    public readonly category: string,
    public readonly correlationId: string,
    public readonly retryable: boolean
  

HubSpot Reliability Patterns

Overview

Production-grade reliability patterns for HubSpot CRM integrations: circuit breaker, retry with Retry-After, graceful degradation, and dead letter queues.

Prerequisites

• @hubspot/api-client installed (has built-in retry)
• Optional: opossum for circuit breaker
• Optional: Redis or database for dead letter queue

Instructions

Step 1: SDK Built-in Retry (First Line of Defense)

import * as hubspot from '@hubspot/api-client';

// The SDK automatically retries 429 and 5xx errors
const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  numberOfApiCallRetries: 3,  // retries with exponential backoff
});
// This handles most transient failures automatically

Step 2: Circuit Breaker for HubSpot API

import CircuitBreaker from 'opossum';

// Circuit breaker wrapping all HubSpot API calls
const hubspotBreaker = new CircuitBreaker(
  async <T>(operation: () => Promise<T>): Promise<T> => operation(),
  {
    timeout: 15000,                // 15s timeout per call
    errorThresholdPercentage: 50,  // open after 50% failure rate
    resetTimeout: 30000,           // try again after 30s
    volumeThreshold: 5,            // need 5+ calls before evaluating
    rollingCountTimeout: 60000,    // 60s rolling window
  }
);

// Monitor circuit state
hubspotBreaker.on('open', () => {
  console.warn('[HubSpot] Circuit OPEN -- requests failing fast');
  // Alert team: HubSpot integration degraded
});

hubspotBreaker.on('halfOpen', () => {
  console.info('[HubSpot] Circuit HALF-OPEN -- testing recovery');
});

hubspotBreaker.on('close', () => {
  console.info('[HubSpot] Circuit CLOSED -- normal operation');
});

// Usage
async function resilientHubSpotCall<T>(operation: () => Promise<T>): Promise<T> {
  return hubspotBreaker.fire(operation) as Promise<T>;
}

// Example
const contacts = await resilientHubSpotCall(() =>
  client.crm.contacts.basicApi.getPage(10, undefined, ['email'])
);

Step 3: Graceful Degradation

// Serve cached/fallback data when HubSpot is unavailable
import { LRUCache } from 'lru-cache';

const fallbackCache = new LRUCache<string, any>({
  max: 10000,
  ttl: 30 * 60 * 1000, // 30 minutes
});

async function withFallback<T>(
  cacheKey: string,
  operation: () => Promise<T>,
  fallback?: T
): Promise<{ data: T; source: 'live' | 'cache' | 'fallback' }> {
  try {
    const data = await resilientHubSpotCall(operation);
    fallbackCache.set(cacheKey, data);
    return { data, source: 'live' };
  } catch (error) {
    // Try cache first

HubSpot SDK Patterns

Overview

Production-ready patterns for the @hubspot/api-client SDK covering typed wrappers, error handling, batch operations, and pagination.

Prerequisites

• @hubspot/api-client v13+ installed
• TypeScript 5+ with strict mode
• Understanding of HubSpot CRM object model

Instructions

Step 1: Typed Client Wrapper

// src/hubspot/client.ts
import * as hubspot from '@hubspot/api-client';
import type {
  SimplePublicObjectInputForCreate,
  SimplePublicObject,
  PublicObjectSearchRequest,
} from '@hubspot/api-client/lib/codegen/crm/contacts';

interface HubSpotConfig {
  accessToken: string;
  retries?: number;
}

let instance: hubspot.Client | null = null;

export function getClient(config?: HubSpotConfig): hubspot.Client {
  if (!instance) {
    instance = new hubspot.Client({
      accessToken: config?.accessToken || process.env.HUBSPOT_ACCESS_TOKEN!,
      numberOfApiCallRetries: config?.retries ?? 3,
    });
  }
  return instance;
}

Step 2: Error Classification

// src/hubspot/errors.ts
export class HubSpotApiError extends Error {
  constructor(
    message: string,
    public readonly statusCode: number,
    public readonly category: string,
    public readonly correlationId: string,
    public readonly retryable: boolean
  ) {
    super(message);
    this.name = 'HubSpotApiError';
  }
}

export function classifyError(error: any): HubSpotApiError {
  const status = error?.code || error?.statusCode || error?.response?.status || 500;
  const body = error?.body || error?.response?.body || {};
  const correlationId = body.correlationId || 'unknown';

  const retryable = [429, 500, 502, 503, 504].includes(status);

  const categoryMap: Record<number, string> = {
    400: 'VALIDATION_ERROR',
    401: 'AUTHENTICATION_ERROR',
    403: 'AUTHORIZATION_ERROR',
    404: 'NOT_FOUND',
    409: 'CONFLICT',
    429: 'RATE_LIMIT',
    500: 'INTERNAL_ERROR',
  };

  return new HubSpotApiError(
    body.message || error.message || 'Unknown HubSpot error',
    status,
    categoryMap[status] || 'UNKNOWN',
    correlationId,
    retryable
  );
}

// Usage wrapper
export async function safeCall<T>(operation: () => Promise<T>): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    throw classifyError(error);
  }
}

Step 3: Typed CRM Operations

// src/hubspot/contacts.ts
import * as hubspot from '@hubspot/api-client';
import type { SimplePublicObject } from '@hubspot/api-client/lib/codegen/crm/contacts';
import { getClient } from './client';
import { safeCall } from './errors';

// Define your contact properties as a

HubSpot Security Basics

Overview

Security best practices for HubSpot private app tokens, OAuth scopes, webhook signature verification, and secret management.

Prerequisites

• HubSpot private app or OAuth app configured
• Understanding of environment variables and secret management

Instructions

Step 1: Least-Privilege Scopes

Only request the scopes your integration actually uses:

Never use: Do not grant all scopes. If you regenerate a private app token, the old token is immediately revoked.

Step 2: Token Storage

# .env (NEVER commit)
HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
HUBSPOT_WEBHOOK_SECRET=your-webhook-secret

# .gitignore
.env
.env.local
.env.*.local

// Validate token is present at startup
function validateConfig(): void {
  if (!process.env.HUBSPOT_ACCESS_TOKEN) {
    throw new Error('HUBSPOT_ACCESS_TOKEN is required. See .env.example');
  }
  // Never log the token
  console.log('HubSpot: Token configured', {
    prefix: process.env.HUBSPOT_ACCESS_TOKEN.substring(0, 8) + '...',
  });
}

Step 3: Webhook Signature Verification (v3)

HubSpot sends webhooks with signature verification headers:

import crypto from 'crypto';
import express from 'express';

// HubSpot v3 signature verification
// Header: X-HubSpot-Signature-v3
function verifyHubSpotSignatureV3(
  requestBody: string,
  signature: string,
  timestamp: string,
  clientSecret: string,
  requestUri: string,
  method: string = 'POST'
): boolean {
  // Reject if timestamp is older than 5 minutes (replay protection)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    console.warn('HubSpot webhook timestamp too old');
    return false;
  }

  // v3: HMAC SHA-256 o

HubSpot Upgrade & Migration

Overview

Guide for upgrading @hubspot/api-client SDK versions and migrating from legacy HubSpot APIs to the current CRM v3 API.

Prerequisites

• Current @hubspot/api-client installed
• Git for version control
• Test suite available
• Staging environment for validation

Instructions

Step 1: Check Current Version and Available Updates

# Current version
npm list @hubspot/api-client

# Latest available
npm view @hubspot/api-client version

# See changelog
npm view @hubspot/api-client versions --json | tail -10

Step 2: Review Breaking Changes

Key breaking changes in @hubspot/api-client:

Step 3: Create Upgrade Branch and Update

git checkout -b chore/upgrade-hubspot-api-client
npm install @hubspot/api-client@latest
npm test

Step 4: Common Migration Patterns

API Key to Access Token (v9 -> v10+)

// BEFORE (deprecated -- API keys removed in v10)
const client = new hubspot.Client({ apiKey: 'your-api-key' });

// AFTER (use private app access token)
const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
});

Associations v3 to v4 (v11 -> v12+)

// BEFORE (v3 associations)
await client.crm.contacts.associationsApi.create(
  contactId, 'companies', companyId, 'contact_to_company'
);

// AFTER (v4 associations)
await client.crm.associations.v4.basicApi.create(
  'contacts', contactId, 'companies', companyId,
  [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 1 }]
);

Legacy Contact API to CRM v3

// BEFORE (legacy /contacts/v1/)
const response = await fetch(
  `https://api.hubapi.com/contacts/v1/contact/email/${email}/profile`,
  { headers: { Authorization: `Bearer ${token}` } }
);

// AFTER (CRM v3 search)
const result = await client.crm.contacts.searchApi.doSearch({
  filterGroups: [{
    filters: [{ propertyName: 'email', operator: 'EQ', value: email }],
  }],
  properties: ['firstname', 'lastname', &

HubSpot Webhooks & Events

Overview

Set up HubSpot webhook subscriptions for CRM events (contact/company/deal creation, updates, deletions) with v3 signature verification and idempotent event handling.

Prerequisites

• HubSpot public app (webhooks require a public app, not a private app)
• Client secret from your app settings (for signature verification)
• HTTPS endpoint accessible from the internet
• Optional: Redis or database for idempotency

Instructions

Step 1: Understand HubSpot Webhook Events

HubSpot sends webhook events as batches of CRM change notifications:

[
  {
    "eventId": 100,
    "subscriptionId": 1234,
    "portalId": 12345678,
    "appId": 98765,
    "occurredAt": 1711234567890,
    "subscriptionType": "contact.propertyChange",
    "attemptNumber": 0,
    "objectId": 123,
    "propertyName": "lifecyclestage",
    "propertyValue": "marketingqualifiedlead",
    "changeSource": "CRM",
    "sourceId": "userId:12345"
  }
]

Available subscription types:

• contact.creation, contact.deletion, contact.propertyChange, contact.privacyDeletion
• company.creation, company.deletion, company.propertyChange
• deal.creation, deal.deletion, deal.propertyChange
• ticket.creation, ticket.deletion, ticket.propertyChange
• contact.merge, company.merge, deal.merge
• contact.associationChange, company.associationChange, deal.associationChange

Step 2: Set Up Webhook Endpoint with Signature Verification

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Use raw body for signature verification
app.post('/webhooks/hubspot',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // Verify signature (v3)
    const signature = req.headers['x-hubspot-signature-v3'] as string;
    const timestamp = req.headers['x-hubspot-request-timestamp'] as string;

    if (!signature || !timestamp) {
      // Fall back to v2 signature
      const sigV2 = req.headers['x-hubspot-signature'] as string;
      if (!verifySignatureV2(req.body.toString(), sigV2)) {
        return res.status(401).json({ error: 'Invalid signature' });
      }
    } else {
      const requestUri = `https://${req.headers.host}${req.originalUrl}`;
      if (!verifySignatureV3(req.body.toString(), signature,