playbooks

home / skills / xfstudio / skills / hubspot-integration

hubspot-integration skill

/hubspot-integration

This skill helps you implement robust HubSpot CRM integration patterns with OAuth, private apps, batch CRUD, and webhooks in Node.js or Python.

npx playbooks add skill xfstudio/skills --skill hubspot-integration

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.0 KB
---
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. Use when: hubspot, hubspot api, hubspot crm, hubspot integration, contacts api."
source: vibeship-spawner-skills (Apache 2.0)
---

# HubSpot Integration

## Patterns

### OAuth 2.0 Authentication

Secure authentication for public apps

### Private App Token

Authentication for single-account integrations

### CRM Object CRUD Operations

Create, read, update, delete CRM records

## Anti-Patterns

### ❌ Using Deprecated API Keys

### ❌ Individual Requests Instead of Batch

### ❌ Polling Instead of Webhooks

## ⚠️ Sharp Edges

| Issue | Severity | Solution |
|-------|----------|----------|
| Issue | high | See docs |
| Issue | high | See docs |
| Issue | critical | See docs |
| Issue | high | See docs |
| Issue | critical | See docs |
| Issue | medium | See docs |
| Issue | high | See docs |
| Issue | medium | See docs |

Overview

This skill codifies expert patterns for integrating with HubSpot CRM, covering authentication, CRM object operations, batch processing, webhooks, and custom objects. It includes practical guidance for both Node.js and Python SDKs and highlights common anti-patterns and integration pitfalls. Use it to build reliable, secure, and scalable HubSpot integrations that follow best practices.

How this skill works

The skill documents secure OAuth 2.0 flows for public apps and private app token usage for single-account integrations. It shows CRUD patterns for contacts, companies, deals, and custom objects, plus efficient batch operations and webhook management. Concrete SDK examples and recommendations reduce API usage, avoid deprecated methods, and improve error handling and retries.

When to use it

  • Building or modernizing a HubSpot integration for contacts, companies, deals, or custom objects
  • Implementing OAuth 2.0 public app authentication or private app tokens for single-account access
  • Optimizing API usage with batch operations and minimizing rate-limit impact
  • Replacing polling-based syncs with webhook-driven flows
  • Adding webhook receivers, verifying signatures, and handling event retries

Best practices

  • Prefer OAuth 2.0 for multi-account apps; use private app tokens only for single-account services
  • Use batch endpoints to reduce request volume and handle partial failures with retries
  • Register and verify webhooks; handle retries and idempotency for event processing
  • Avoid deprecated API keys and endpoints; keep SDKs up to date with official client libraries
  • Model associations explicitly and validate foreign keys before writes to prevent orphaned records

Example use cases

  • A SaaS product syncing user accounts to HubSpot contacts via webhook events and batch updates
  • A marketing tool that authenticates customers via OAuth 2.0 and reads custom object data for segmentation
  • A data pipeline that upserts companies and deals in bulk using Node.js or Python SDKs to minimize rate limits
  • A support platform that receives ticket events through HubSpot webhooks and applies idempotent updates

FAQ

When should I use OAuth 2.0 vs a private app token?

Use OAuth 2.0 for apps that need access to multiple customer accounts. Use private app tokens for integrations limited to a single HubSpot account or internal tooling.

How do I avoid hitting rate limits?

Batch operations, exponential backoff on retries, request throttling, and prioritizing webhooks over polling reduce API load and rate-limit exposure.

How do I ensure webhook deliveries are secure?

Verify the signature header sent by HubSpot, use HTTPS endpoints, and implement idempotent handlers to safely reprocess retries.