Wiring AI Into HubSpot: A Real-World Pattern
The integration patterns that work — and the anti-patterns that cause data corruption.
We've integrated LLMs into HubSpot for dozens of clients. The same anti-patterns sink projects again and again. Here's the architecture that survives contact with reality.
Architecture in one paragraph
HubSpot webhook fires → lands in your message queue (SQS, Pub/Sub, BullMQ) → background worker picks up, calls the LLM, enriches the response, writes back to HubSpot via the v3 OAuth API → logs the round trip with a deterministic correlation ID. Never call the LLM synchronously inside the webhook handler.
Five rules that prevent data corruption
- Use webhook triggers, not polling. Polling at scale runs into HubSpot rate limits and creates duplicate work.
- OAuth v3 with refresh tokens stored in your secrets manager. API keys are deprecated and were never per-user accountable.
- Async via queue, always. Webhooks have a 5-second timeout; LLM calls regularly exceed it.
- Tag every AI-generated field with a custom property (e.g.
ai_generated_score,ai_last_updated_at) so humans can audit and override. - Write back idempotently. Include a hash of inputs as a custom property; skip the update if the hash hasn't changed.
The most expensive mistake
Letting the AI overwrite human-edited fields without checking. The day a sales rep can't tell apart "field I wrote" vs "field the bot guessed" is the day CRM data quality dies and the rep loses trust in the system. We solve this with a "last_human_edit_at" timestamp — if it's newer than the AI's last attempt, the AI write is rejected and queued for review.
Useful properties to add to every Contact
ai_summary— 2-3 sentence rolling summary of recent activity.ai_next_best_action— recommended outreach with confidence score.ai_intent_signals— array of detected buying signals.ai_last_run_at— for cache invalidation and debugging.
Bottom line
Treat HubSpot as the system of record, not the AI. The AI is a read-mostly enrichment layer with a strict audit trail. Build it that way and you'll keep both the data and the sales team happy.