HubSpot Integration

Bi-directional CRM sync between Renewa One and HubSpot. The most complex integration in the system — 14 backend service files, 7 database tables, and a full sync engine with mapping layer.

Architecture

Layer	Location
OAuth	backend/src/services/hubspot/auth.ts
Webhook receiver	backend/src/routes/hubspot/webhook.ts
Sync engine	backend/src/services/hubspot/sync-engine/
Mapping system	backend/src/services/hubspot/mapping/
Event handlers	backend/src/services/hubspot/event-handlers/
Main service	backend/src/services/hubspot/hubspot-sync.service.ts
Admin service	backend/src/services/hubspot/hubspot-sync-admin.service.ts
Sync queue	backend/src/lib/jobs/hubspot-sync-queue.ts
Frontend admin	frontend/src/pages/admin/HubSpot.tsx

Synced Entities

Renewa One	HubSpot Object
Contacts	Contacts
Companies	Companies
Leads	Leads
Quotes	Deals
Products	Line Items

Sync Engine

Located at backend/src/services/hubspot/sync-engine/:

Module	Purpose
entity-registry	Registers syncable entity types and their configurations
sync-operations	Core sync logic (create, update, delete)
batch-sync	Bulk sync operations for initial import/export
apply-mappings	Applies property mappings during sync

Mapping System

Located at backend/src/services/hubspot/mapping/:

Module	Purpose
property-mapping	Maps Renewa fields to HubSpot properties
enum-mapping	Maps enum values between systems
type-inference	Infers field types for unmapped properties
value-transformer	Transforms values during sync (dates, currencies, etc.)
mapping-suggestion	Auto-suggests mappings based on field names
mapping-cache	Caches resolved mappings for performance

Database Tables

Table	Purpose
hubspotConfig	OAuth tokens (encrypted), sync settings
hubspotPropertyMappings	Field-to-property mapping definitions
hubspotEnumValueMappings	Enum value translations
hubspotAssociationLabels	HubSpot association label definitions
hubspotAssociations	Record-level associations
hubspotSyncLog	Sync operation audit trail
hubspotWebhookLog	Inbound webhook event log

Security

• OAuth tokens: Encrypted at rest using ENCRYPTION_MASTER_KEY (AES-256-GCM)
• Token refresh: Automatic, 5 minutes before expiry
• Webhook validation: HMAC-SHA256 v3 signatures with 5-minute timestamp window
• Secrets: HUBSPOT_CLIENT_ID (public), HUBSPOT_CLIENT_SECRET (webhook signature validation)

Background Processing

Sync operations are queued via Background Jobs (BullMQ) at backend/src/lib/jobs/hubspot-sync-queue.ts to avoid blocking API responses during large sync operations.

Related

• Background Jobs — async sync queue processing
• Validation Pattern — input validation for synced data
• Admin Dashboard — HubSpot configuration UI
• External Integrations — other third-party integrations
• Database Architecture — encrypted storage design