HubSpot Integration Service 🚀

A production-ready backend microservice to integrate with HubSpot CRM. Sync contacts, deals, and companies, handle webhooks, and access synced data via REST APIs.

---

✨ Features

• Authentication: Secure HubSpot API key integration
• Data Sync: Automatic sync of contacts, deals, and companies
• Webhook Handling: Receive and process real-time HubSpot events
• REST API: Clean and documented endpoints
• Error Handling: Exponential backoff and rate-limit support
• Database: PostgreSQL with TypeORM
• Logging: Structured logging with Winston
• TypeScript: Full type safety

---

📋 Prerequisites

• Node.js 18+
• PostgreSQL 15+
• HubSpot Personal Access Key

---

🛠️ Setup

1. Clone and Install

git clone <your-repo-url>
cd HubSpot_Integration
npm install

2. Environment Variables

Copy .env.example to .env and update the values:

PORT=3000
NODE_ENV=development

DB_HOST=localhost
DB_PORT=5432
DB_USER=harsh
DB_PASSWORD=1234@Harsh
DB_NAME=HubspotCRM

HUBSPOT_API_KEY=your-hubspot-api-key
HUBSPOT_BASE_URL=https://api.hubapi.com

WEBHOOK_SECRET=your-webhook-secret
BASE_URL=http://localhost:3000

3. Database Setup

Local PostgreSQL:

CREATE DATABASE HubspotCRM;

If PostgreSQL is running in Docker:

docker exec -it mypostgres psql -U harsh -d HubspotCRM

4. Build and Run

# Build TypeScript
npm run build

# Development
npm run dev

# Production
npm start

Server runs at http://localhost:3000.

---

📡 API Endpoints

Health Check

GET /api/health

Sync

POST /api/sync           # Sync all entities
POST /api/sync/contacts  # Sync contacts
POST /api/sync/deals     # Sync deals
POST /api/sync/companies # Sync companies

Contacts

GET /api/contacts?limit=50&offset=0&email=test@example.com
GET /api/contacts/:id

Deals

GET /api/deals?stage=qualifiedtobuy&minAmount=1000
GET /api/deals/:id

Companies

GET /api/companies?industry=Technology
GET /api/companies/:id

Webhooks

POST /api/webhook                  # Receive events
GET /api/webhooks                  # List received events
GET /api/webhook-subscriptions     # List subscriptions
POST /api/webhook-subscriptions    # Create subscription
DELETE /api/webhook-subscriptions/:id  # Delete subscription

⚠️ Webhook events and HubSpot UI screenshots are attached for reference. Note: Don’t forget to create subscriptions for Contacts, Deals, and other relevant objects in HubSpot to ensure all events are captured correctly.

---

🔐 Webhook Setup

1. Register via API

curl -X POST http://localhost:3000/api/webhook-subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "contact.creation",
    "webhookUrl": "https://your-domain.com/api/webhook"
  }'

2. Register via HubSpot UI HubSpot → Settings → Integrations → Private Apps → Webhooks → Add your webhook URL

3. Security Set WEBHOOK_SECRET in .env and configure HubSpot to use the same secret.

---

🏗️ Architecture

src/
├── config/          # Config (DB, logger)
├── controllers/     # Request handlers
├── entities/        # TypeORM entities
├── middleware/      # Express middleware
├── routes/          # API routes
├── services/        # Business logic (HubSpot sync)
└── index.ts         # Entry point

Highlights:

• Idempotent updates using hubspotId
• Exponential backoff for API retries
• Structured logging with Winston
• Centralized error handling middleware
• Rate-limiting protection

---

🧪 Testing

npm test
npm run test:watch

---

📸 Screenshots

Webhook and Hubspot Events

---

---

Shows sample webhook and Hubspot events received in the service.

HubSpot UI

---

---

Shows the Private App & Webhooks configuration in HubSpot.

---

📚 HubSpot Documentation

• CRM API
• Webhooks
• Rate Limits

---

🐛 Troubleshooting

• Database issues: Verify PostgreSQL is running locally or via Docker
• Webhook issues: Ensure URL is publicly accessible & check GET /api/webhooks
• API errors: Confirm HubSpot API key and check rate limits

---

📄 License

MIT

👤 Author

Build by Harsh