HubSpot Integration Skill

A Claude Code skill for integrating HubSpot CRM into your applications — covering OAuth authentication, contact/deal management, custom properties, workflow automation, and webhook handling.

When to Use This Skill

Choose this skill when:

• Integrating HubSpot CRM data into your application
• Building custom HubSpot apps with OAuth authentication
• Syncing contacts, deals, or companies between systems
• Creating custom properties and associations in HubSpot
• Handling HubSpot webhooks for real-time event processing
• Automating CRM workflows programmatically

Consider alternatives when:

• You need a simple form submission (use HubSpot's embedded forms)
• You need email marketing only (use HubSpot's native tools)
• You need a different CRM (use Salesforce, Pipedrive, etc.)

Quick Start

Copy
# Install HubSpot client
npm install @hubspot/api-client

Copy
import { Client } from '@hubspot/api-client';

// Private app authentication
const hubspot = new Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN });

// Create a contact
const contact = await hubspot.crm.contacts.basicApi.create({
  properties: {
    email: 'john@example.com',
    firstname: 'John',
    lastname: 'Doe',
    company: 'Acme Corp'
  }
});

// Search contacts
const results = await hubspot.crm.contacts.searchApi.doSearch({
  filterGroups: [{
    filters: [{
      propertyName: 'email',
      operator: 'EQ',
      value: 'john@example.com'
    }]
  }],
  properties: ['email', 'firstname', 'lastname']
});

Core Concepts

CRM Objects

Object	Purpose	Key Properties
Contacts	People in your CRM	email, firstname, lastname, phone
Companies	Organizations	name, domain, industry, revenue
Deals	Sales opportunities	dealname, amount, pipeline, dealstage
Tickets	Support requests	subject, content, hs_pipeline, hs_pipeline_stage
Custom Objects	Domain-specific entities	User-defined properties

OAuth 2.0 Flow

Copy
// OAuth authorization URL
const authUrl = `https://app.hubspot.com/oauth/authorize?` +
  `client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=crm.objects.contacts.read`;

// Exchange code for tokens
const tokenResponse = await hubspot.oauth.tokensApi.create(
  'authorization_code', code, REDIRECT_URI, CLIENT_ID, CLIENT_SECRET
);

// Refresh tokens before expiry
const refreshed = await hubspot.oauth.tokensApi.create(
  'refresh_token', undefined, undefined, CLIENT_ID, CLIENT_SECRET, refreshToken
);

Webhook Handling

Copy
import crypto from 'crypto';

// Verify webhook signature
function verifyWebhook(req: Request, secret: string): boolean {
  const signature = req.headers['x-hubspot-signature-v3'];
  const timestamp = req.headers['x-hubspot-request-timestamp'];
  const body = JSON.stringify(req.body);
  const hash = crypto.createHmac('sha256', secret)
    .update(`${req.method}${req.url}${body}${timestamp}`)
    .digest('hex');
  return hash === signature;
}

Configuration

Parameter	Type	Default	Description
auth_type	string	"private_app"	Authentication: private_app, oauth
access_token	string	—	Private app access token
client_id	string	—	OAuth client ID (for public apps)
client_secret	string	—	OAuth client secret
scopes	array	["crm.objects.contacts.read"]	OAuth permission scopes
api_version	string	"v3"	HubSpot API version
rate_limit	number	100	Requests per 10-second window

Best Practices

1. Use private app tokens for internal integrations — private app tokens are simpler than OAuth and sufficient for single-account integrations; use OAuth only when building apps for multiple HubSpot accounts.

2. Batch API calls to respect rate limits — HubSpot allows 100 requests per 10 seconds; use batch endpoints (/batch/create, /batch/update) to process multiple records in one API call.

3. Always verify webhook signatures — check x-hubspot-signature-v3 to ensure webhooks are actually from HubSpot; unverified webhooks can be spoofed by attackers.

4. Use search API instead of listing all records — listing endpoints paginate through all records; the search API with filters returns only matching records, reducing API calls and data transfer.

5. Store HubSpot record IDs in your database — maintain a mapping between your internal IDs and HubSpot record IDs to avoid search lookups on every sync operation.

Common Issues

Rate limit exceeded (429 errors) — Implement exponential backoff and use batch endpoints. For bulk imports, use the HubSpot Import API instead of individual API calls.

Webhook events arrive out of order — HubSpot doesn't guarantee webhook delivery order. Use the occurredAt timestamp in webhook payloads to determine event ordering and handle idempotently.

OAuth tokens expire without refresh — Access tokens expire after 30 minutes. Implement automatic token refresh using the refresh token before each API call, and store refreshed tokens securely.