Skip to main content

​
Overview

The HubSpot integration automatically syncs leads captured through your chat widget directly to your HubSpot CRM as contacts. When a customer submits their information, Vaile creates or updates their contact record in HubSpot with all lead details.

​
What Gets Synced

When a lead is captured via your chat widget, Vaile sends the following information to HubSpot:
  • Contact Information: Name, email, phone number
  • Lead Details: Status, priority, source
  • Vehicle Interest: Make, model, and budget range
  • Conversation Notes: Customer inquiries and preferences
  • Dealership Context: Which dealership location the lead is for
Contacts are automatically set to “Lead” lifecycle stage in HubSpot, making it easy to track and nurture new prospects.

​
Setup

​
Prerequisites

Before connecting HubSpot, ensure you have:
  • HubSpot Account with admin access
  • CRM Permissions to create and modify contacts
  • Custom Properties created in HubSpot (see below)

​
1. Create Custom Properties in HubSpot

HubSpot doesn’t have default fields for automotive-specific data. You’ll need to create custom contact properties:
Type: Single-line text Internal name: vehicle_of_interest Label: Vehicle of Interest Description: The vehicle the customer is interested in
Type: Single-line text Internal name: budget_range Label: Budget Range Description: Customer’s budget range for vehicle purchase
Type: Dropdown Internal name: lead_priority Label: Lead Priority Options: high, medium, low Description: Priority level of this lead
Type: Single-line text Internal name: lead_origin_channel Label: Lead Origin Channel Description: Channel where the lead originated (e.g., chat_widget)
Type: Single-line text Internal name: dealership_name Label: Dealership Name Description: Name of the dealership this lead is for
Type: Single-line text Internal name: dealership_slug Label: Dealership Slug Description: Dealership identifier
To create custom properties in HubSpot:
  1. Go to Settings → Properties
  2. Select Contact properties
  3. Click Create property
  4. Add each property listed above

​
2. Connect HubSpot

Navigate to Integrations → Events in your Vaile dashboard.
  1. In the webhook portal, find Connectors section
  2. Locate HubSpot CRM connector
  3. Click Connect to HubSpot
  4. Authorize Vaile to access your HubSpot account
  5. Review and approve the requested permissions
You must be a HubSpot admin to authorize the integration. The integration requires permissions to create and update contacts in your CRM.

​
3. Select Event Types

After connecting, select which events should sync to HubSpot:
  • ✅ Lead Captured - Recommended (syncs all captured leads)
  • 🔜 Carousel Clicked - Coming soon
  • 🔜 Session Initiated - Coming soon
Start with “Lead Captured” only. You can add more event types later as they become available.

​
4. Test the Integration

  1. Open your chat widget on your website
  2. Fill out the lead capture form with test data
  3. Submit the form
  4. Check HubSpot CRM → Contacts for the new contact
  5. Verify all fields are populated correctly

​
How It Works

​
Lead Capture Flow

Customer submits lead form
         ↓
Vaile creates contact & lead
         ↓
Event sent to webhook system
         ↓
HubSpot connector transforms data
         ↓
Contact created/updated in HubSpot

​
Data Mapping

Vaile automatically maps your lead data to HubSpot fields:
Vaile FieldHubSpot Property
Contact NameFirst Name + Last Name
EmailEmail
PhonePhone
Vehicle InterestVehicle of Interest (custom)
Budget RangeBudget Range (custom)
Lead StatusLead Status
PriorityLead Priority (custom)
NotesNotes - Last Contacted
OriginLead Source

​
Lifecycle Stage

All synced contacts are automatically set to “Lead” lifecycle stage, making them easy to identify and nurture in your HubSpot workflows.

​
Managing the Integration

​
Viewing Sync Status

Check webhook delivery status in the Events dashboard:
  1. Go to Integrations → Events
  2. Click Logs tab
  3. Filter by event type: lead.captured.v1
  4. View delivery status for each lead
Successful deliveries show a 200 OK status. Failed deliveries will show error details and retry attempts.

​
Automatic Retries

If HubSpot is temporarily unavailable or returns an error, the webhook system automatically retries delivery:
  • 1st retry: Immediately
  • 2nd retry: 5 seconds
  • 3rd retry: 5 minutes
  • 4th retry: 30 minutes
  • 5th retry: 2 hours
  • Continues for: Up to 3 days

​
Disconnecting HubSpot

To disconnect the integration:
  1. Go to Integrations → Events
  2. Click Connectors
  3. Find HubSpot CRM
  4. Click Disconnect
  5. Confirm disconnection
After disconnecting, new leads will no longer sync to HubSpot. Existing contacts in HubSpot remain unchanged.

​
Troubleshooting

Check:
  • HubSpot connection is active (green status in Events dashboard)
  • Required permissions are granted (check OAuth settings)
  • Custom properties are created in HubSpot
  • No duplicate email exists (HubSpot may update instead of create)
Solution:
  • Review webhook logs for error messages
  • Re-authorize HubSpot connection
  • Verify custom properties exist
Cause: Custom properties not created in HubSpotSolution:
  • Create the missing custom properties (see Setup step 1)
  • New leads will include all fields
  • Existing contacts won’t be updated automatically
Cause: HubSpot uses email as unique identifierBehavior:
  • If email exists: HubSpot updates the existing contact
  • If email is new: HubSpot creates a new contact
  • If email is blank: May create duplicate contacts
Best Practice:
  • Always capture email addresses in lead forms
  • Use HubSpot’s duplicate management tools
Possible causes:
  • OAuth token expired
  • HubSpot account permissions changed
  • Admin revoked access
Solution:
  • Re-connect HubSpot via Events dashboard
  • Verify you have admin permissions
  • Check HubSpot connected apps settings

​
Security & Privacy

​
Data Transmission

  • All data is transmitted securely via HTTPS
  • Webhooks are signed with HMAC signatures
  • HubSpot connection uses OAuth 2.0 authentication

​
Permissions Required

The integration requests these HubSpot permissions:
  • Create/Update Contacts - To sync lead information
  • Read Contacts - To check for duplicates
  • Read Contact Properties - To validate custom fields
Vaile never stores your HubSpot credentials. Authentication is handled securely via OAuth, and tokens are encrypted at rest.

​
Compliance

  • GDPR: Customers can request data deletion via your HubSpot account
  • Data Retention: Follow your HubSpot data retention policies
  • Consent: Ensure lead capture forms include appropriate consent language

​
Advanced: Creating Deals

By default, the integration creates contacts only. If you want to also create deals in HubSpot:
1

Contact Vaile Support

Reach out to [email protected] to request the deal creation feature
2

Provide Deal Settings

Specify your deal pipeline, stage, and default values
3

Custom Transformation

Vaile will configure a custom transformation for your account
4

Test & Deploy

Test with sample leads before enabling for production
Most dealerships start with contacts only and use HubSpot workflows to create deals automatically based on their sales process.

​
Best Practices

  1. Set Up Workflows - Create HubSpot workflows to automatically assign leads to sales reps
  2. Enable Notifications - Configure HubSpot to notify your team of new leads
  3. Monitor Sync Status - Check webhook logs weekly to ensure consistent delivery
  4. Use Lead Scoring - Leverage HubSpot’s lead scoring with the priority field
  5. Create Follow-up Tasks - Use HubSpot automation to schedule follow-ups

​
Need Help?

If you encounter issues or need assistance:
  • Email: [email protected]
  • Dashboard: Use the chat widget in your Vaile dashboard
  • Documentation: Check webhook logs for detailed error messages
Our support team typically responds within 24 hours on business days.