hubspot-product-event-sync

What it does

Pushes backend product events into HubSpot custom contact and company properties using an idempotent, batched update pattern. Includes property verification/creation, per-event idempotency keys, a batching queue with rate limiting, 207 Multi-Status handling with a dead-letter queue, auto-create-on-miss behavior via batch upsert, and rate-limit retry wiring. Designed as a Segment-style integration without Segment, triggerable by specific hubspot-related phrases.

How it works

• Ensures target HubSpot properties exist and have the correct type using an ensureProperty routine; creates properties if absent.
• Designs idempotency keys per event and property (hash of eventId and propertyName); stores processed keys with TTL to avoid reprocessing.
• Reads current values for counter properties, computes absolute next values, writes back, and marks the operation as processed to guarantee idempotency.
• Batches events using a token-bucket style queue: flushes when either 100 events accumulate or after 5 seconds, whichever comes first; performs one batch call using crm/v3/objects/contacts/batch/upsert with idProperty set to email.
• Handles HubSpot 207 responses by routing failed items to a dead-letter queue with context; successes are acknowledged, failures are logged.
• If a contact email is missing, uses batch upsert to auto-create; provides an alternate search+create path if needed to obtain a contactId synchronously before writing other properties.
• Wires rate limiting to respect Retry-After on 429 responses and handles retries accordingly.

When to use it

Use when you need to push server-side behavioral signals (feature usage, session counts, last-seen timestamps, trial milestones) into HubSpot CRM properties so sales/marketing can act on product data without a CDP. Trigger phrases include: "hubspot product events", "sync events to hubspot", "hubspot custom properties", "hubspot event pipeline", "hubspot segment alternative", "push usage data to hubspot".

What it can touch

• HubSpot API endpoints for properties and batch upserts:
  • https://api.hubapi.com/crm/v3/properties/...
  • https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert
  • https://api.hubapi.com/crm/v3/objects/contacts/{contactId}
• Redis (or similar) for idempotency key storage via SETEX and GET.
• External logs/dead-letter queue for failed batch items.

Caveats

• Requires Node.js 18+ or Python 3.10+ and a HubSpot private app token with appropriate scopes.
• Property definitions must be defined prior to writing; if types mismatch, writes may coerce data without error unless validated on the client side.
• Batch partial failures (207) must be parsed to route failed items to DLQ; silent data loss is possible if not handled.
• Idempotency keys are designed per (eventId, propertyName); counter properties require reading current value before computing the absolute next value to ensure idempotent increments.
• Some sections refer to external references/files for full implementation details (e.g., references/event-queue-implementation.md) and are not fully described here.