HubSpot Sync

Sync Keva customer profiles with HubSpot contacts automatically. Keep your customer data synchronized across both systems as tickets flow through Keva.

Prerequisites

Before setting up HubSpot sync:

1. HubSpot account with API access (Free CRM or higher)
2. Keva HubSpot connector connected via OAuth
3. Admin permissions in both HubSpot and Keva

Connect HubSpot

Step 1: Authorize OAuth

1. Go to Settings then Integrations then HubSpot
2. Click Connect
3. Sign in to HubSpot
4. Select your HubSpot portal (if you have multiple)
5. Authorize Keva to access your HubSpot data
6. You'll be redirected back to Keva

Step 2: Verify Connection

After connecting, you should see:

• Connection status: Connected
• Portal ID
• Last sync timestamp

What Gets Synced

Contacts (Primary)

Customer profiles sync to HubSpot Contacts:

Companies (Optional)

Link customers to HubSpot Companies for B2B context:

Deals (Read-Only)

Access deal information for context:

Configure Field Mappings

Access Field Mapping

1. Go to Settings then CRM Sync then HubSpot
2. Click Field Mappings
3. Select object type (Contact, Company)

Add a Mapping

1. Click Add Mapping
2. Select Keva field from dropdown
3. Select HubSpot property from dropdown
4. Choose sync direction:
   • Bidirectional: Syncs both ways
   • To CRM: Keva to HubSpot only
   • From CRM: HubSpot to Keva only
5. Optionally add transformation
6. Click Save

Auto-Mapping (AI-Assisted)

Let Keva suggest mappings based on field names:

1. Click Auto-Map Fields
2. Keva analyzes your HubSpot properties
3. Review suggestions with confidence scores
4. Accept, reject, or modify each mapping
5. Save accepted mappings

Describe Fields

Fetch available HubSpot properties:

1. Click Refresh Properties
2. Keva fetches all Contact/Company properties
3. Use these in your custom mappings

Name Handling

HubSpot uses separate firstname and lastname properties:

• To HubSpot: "Jane Smith" becomes firstname="Jane", lastname="Smith"
• From HubSpot: firstname + lastname becomes "Jane Smith"

The sync handles multi-word names intelligently:

• "Mary Jane Watson" becomes firstname="Mary Jane", lastname="Watson"

Sync Triggers

Automatic (Event-Driven)

Sync happens automatically when:

Deduplication

When creating contacts, Keva prevents duplicates:

1. Searches HubSpot by email first
2. If contact exists, links and updates
3. If not found, creates new contact
4. Stores HubSpot contact ID for future syncs

Manual Sync

Sync a single customer:

1. Go to the ticket or customer profile
2. Click the HubSpot icon in the sidebar
3. Click Sync Now

Batch Sync

Sync all customers:

1. Go to Settings then CRM Sync then HubSpot
2. Click Run Batch Sync
3. Monitor progress (100 customers per batch)

Webhook Setup (Inbound Sync)

To receive real-time updates from HubSpot:

Step 1: Create Private App (Recommended)

In HubSpot:

1. Go to Settings then Integrations then Private Apps
2. Click Create a private app
3. Name: Keva CRM Sync
4. Scopes: Select crm.objects.contacts.read and crm.objects.contacts.write
5. Create app and copy the access token

Step 2: Configure Webhook Subscriptions

Using HubSpot's Webhooks API:

1. Go to Settings then Integrations then Webhooks
2. Or use HubSpot's API to create subscriptions:

POST https://api.hubapi.com/webhooks/v3/{appId}/subscriptions
{
  "eventType": "contact.propertyChange",
  "propertyName": "*",
  "active": true,
  "targetUrl": "https://app.keva.support/api/webhooks/hubspot"
}

Step 3: Configure in Keva

1. Go to Settings then CRM Sync then HubSpot then Webhooks
2. Enter your HubSpot App ID (for signature verification)
3. Save configuration

Webhook Security

Keva verifies HubSpot webhooks using X-HubSpot-Signature-v3:

1. HubSpot signs each webhook request
2. Keva validates signature using your app secret
3. Invalid signatures are rejected with 401

Troubleshooting

"Contact not found" Error

Cause: Email doesn't match any HubSpot contact.

Solution:

1. Verify email format matches exactly
2. Check for leading/trailing spaces
3. HubSpot treats emails case-insensitively

"Property doesn't exist" Error

Cause: Mapped HubSpot property not found.

Solution:

1. Use internal property name, not label (e.g., jobtitle not Job Title)
2. Click Refresh Properties to update available fields
3. Create the property in HubSpot if it's custom

"CONFLICT" Error (409)

Cause: Concurrent update to the same contact.

Solution:

1. Keva automatically retries with exponential backoff
2. If persistent, check for other integrations updating same contacts
3. Review sync frequency settings

"Duplicate contact" Warning

Cause: Contact with same email already exists.

Solution:

1. Keva searches by email before creating
2. If duplicate detected, links to existing contact
3. Check HubSpot for duplicate contacts and merge if needed

Sync Showing "Pending" Status

Cause: Background job not processing.

Solution:

1. Check Inngest dashboard for function status
2. Verify HubSpot OAuth token is valid
3. Reconnect HubSpot if token expired (tokens refresh automatically)

Webhook Not Triggering

Cause: Webhook subscription not active or misconfigured.

Solution:

1. Verify subscription is active in HubSpot
2. Check target URL is exactly https://app.keva.support/api/webhooks/hubspot
3. Test with HubSpot's webhook testing tool
4. Check Keva logs for incoming webhook requests

Rate Limiting (429 Error)

Cause: Too many API requests to HubSpot.

Solution:

1. Keva automatically implements retry with backoff
2. Batch sync is rate-limited to 100 customers per run
3. Wait and retry if doing manual bulk operations

Best Practices

Initial Setup

1. Connect via OAuth - More secure than API key
2. Start with default mappings - Customize after testing
3. Test with sandbox - Use HubSpot's test portal first

Field Mapping

1. Map essential fields first - Email, name, company
2. Use bidirectional carefully - Prevents data conflicts
3. Add defaults for required fields - Prevents validation errors

Performance

1. Schedule batch sync during off-hours - Respects rate limits
2. Monitor sync history regularly - Catch errors early
3. Clean up failed syncs - Resolve mapping issues promptly

Data Quality

1. Validate email formats - HubSpot requires valid emails
2. Handle duplicates - Review and merge in HubSpot
3. Use consistent naming - Helps AI identify customers

API Reference

Trigger Sync Programmatically

POST /api/crm/hubspot/sync
Authorization: Bearer keva_live_xxx
Content-Type: application/json
 
{
  "customerId": "uuid-of-customer",
  "connectorId": "uuid-of-hubspot-connector"
}

Get Available Properties

GET /api/crm/hubspot/describe?object=Contact
Authorization: Bearer keva_live_xxx

Response

{
  "properties": [
    {
      "name": "email",
      "label": "Email",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "firstname",
      "label": "First Name",
      "type": "string",
      "fieldType": "text"
    }
  ]
}

Test Field Mapping

POST /api/crm/hubspot/test-mapping
Authorization: Bearer keva_live_xxx
Content-Type: application/json
 
{
  "connectorId": "uuid",
  "customerId": "uuid",
  "dryRun": true
}

Response

{
  "preview": {
    "email": "jane@example.com",
    "firstname": "Jane",
    "lastname": "Smith",
    "company": "Acme Inc"
  },
  "warnings": [],
  "errors": []
}

Comparison with Salesforce

Choose HubSpot if:

• You're on HubSpot's free CRM
• You want simpler setup
• You need marketing automation context

Choose Salesforce if:

• You're enterprise-focused
• You need complex workflow rules
• You have existing Salesforce infrastructure