Integration Guide

HubSpot Integration Guide

Sync qualified leads and conversation context into HubSpot with clear field mapping and retry-safe webhook behavior.

Prerequisites

  • HubSpot private app token with CRM write scope
  • HoverBot workspace admin access
  • Defined lead qualification fields and ownership rules

Implementation Steps

  1. Create a HubSpot private app and copy API token
  2. Configure field mapping in HoverBot (email, phone, intent, score)
  3. Enable lead sync trigger on “qualified” conversation state
  4. Set retry policy for transient HubSpot API failures
  5. Validate contact creation and duplicate merge behavior

Example Payload

{
  "event": "lead.qualified",
  "lead": {
    "email": "buyer@example.com",
    "phone": "+1-555-0100",
    "qualificationScore": 82,
    "intent": "product_demo",
    "conversationUrl": "https://app.hoverbot.ai/conversations/abc123"
  }
}

Validation Checklist

  • Lead is created once (idempotent key enforced)
  • Qualification score and intent map to expected properties
  • Conversation transcript link is accessible for handoff context
  • Failed requests are logged and retried with backoff

Need help with mapping?

Request Integration SupportZendesk Guide