| name | hubspot-integration |
| description | Expert patterns for HubSpot CRM integration including OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. Covers Node.js and Python SDKs. |
| category | Business & Marketing |
| source | antigravity |
| tags | ["python","node","api","ai","automation","template","security","stripe","rag","marketing"] |
| url | https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/hubspot-integration |
HubSpot Integration
Expert patterns for HubSpot CRM integration including OAuth authentication,
CRM objects, associations, batch operations, webhooks, and custom objects.
Covers Node.js and Python SDKs.
Patterns
OAuth 2.0 Authentication
Secure authentication for public apps
When to use: Building public app or multi-account integration
Template
// OAuth 2.0 flow for HubSpot
import { Client } from "@hubspot/api-client";
// Environment variables
const CLIENT_ID = process.env.HUBSPOT_CLIENT_ID;
const CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
const REDIRECT_URI = process.env.HUBSPOT_REDIRECT_URI;
const SCOPES = "crm.objects.contacts.read crm.objects.contacts.write";
// Step 1: Generate authorization URL
function getAuthUrl(): string {
const authUrl = new URL("https://app.hubspot.com/oauth/authorize");
authUrl.searchParams.set("client_id", CLIENT_ID);
authUrl.searchParams.set("redirect_uri", REDIRECT_URI);
authUrl.searchParams.set("scope", SCOPES);
return authUrl.toString();
}
// Step 2: Handle OAuth callback
async function handleOAuthCallback(code: string) {
const response = await fetch("https://api.hubapi.com/oauth/v1/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "authorization_code",
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
redirect_uri: REDIRECT_URI,
code: code,
}),
});
const tokens = await response.json();
// {
// access_token: "xxx",
// refresh_token: "xxx",
// expires_in: 1800 // 30 minutes
// }
// Store tokens securely
await storeTokens(tokens);
return tokens;
}
// Step 3: Refresh access token (before expiry)
async function refreshAccessToken(refreshToken: string) {
const response = await fetch("https://api.hubapi.com/oauth/v1/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "refresh_token",
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
refresh_token: refreshToken,
}),
});
return response.json();
}
// Step 4: Create authenticated client
function createClient(accessToken: string): Client {
const hubspotClient = new Client({ accessToken });
return hubspotClient;
}
Notes
- Access tokens expire in 30 minutes
- Refresh tokens before expiry
- Store refresh tokens securely
- Rotate tokens every 6 months
Private App Token
Authentication for single-account integrations
When to use: Building internal integration for one HubSpot account
Template
// Private App Token - simpler for single account
import { Client } from "@hubspot/api-client";
// Create client with private app token
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN,
});
// Private app tokens don't expire
// But should be rotated every 6 months for security
// Example: Get contacts
async function getContacts() {
try {
const response = await hubspotClient.crm.contacts.basicApi.getPage(
100, // limit
undefined, // after cursor
["firstname", "lastname", "email", "phone"], // properties
);
return response.results;
} catch (error) {
if (error.code === 429) {
// Rate limited - implement backoff
const retryAfter = error.headers?.["retry-after"] || 10;
await sleep(retryAfter * 1000);
return getContacts();
}
throw error;
}
}
// Python equivalent
// from hubspot import HubSpot
//
// client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])
//
// contacts = client.crm.contacts.basic_api.get_page(
// limit=100,
// properties=["firstname", "lastname", "email"]
// )
Notes
- Private app tokens don't expire
- All private apps share daily rate limit
- Each private app has own burst limit
- Recommended: Rotate every 6 months
CRM Object CRUD Operations
Create, read, update, delete CRM records
When to use: Working with contacts, companies, deals, tickets
Template
import { Client } from "@hubspot/api-client";
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_TOKEN,
});
// CREATE contact
async function createContact(data: {
email: string;
firstname: string;
lastname: string;
}) {
const response = await hubspotClient.crm.contacts.basicApi.create({
properties: {
email: data.email,
firstname: data.firstname,
lastname: data.lastname,
},
});
return response;
}
// READ contact by ID
async function getContact(contactId: string) {
const response = await hubspotClient.crm.contacts.basicApi.getById(
contactId,
["firstname", "lastname", "email", "phone", "company"],
);
return response;
}
// UPDATE contact
async function updateContact(contactId: string, properties: object) {
const response = await hubspotClient.crm.contacts.basicApi.update(
contactId,
{ propertie
