Skip to main content

Integrations

LeadVibe offers multiple ways to integrate with your existing tools and workflows.

MCP Server (Model Context Protocol)​

The LeadVibe Lead Intelligence MCP Server provides AI assistants like Claude with direct access to your lead data, scoring, and engagement patterns.

What is MCP?​

Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external data sources and tools. The LeadVibe MCP Server enables AI agents to query your lead intelligence data using natural language.

Capabilities​

Once configured, AI assistants can:

  • Query lead scores and engagement levels
  • Access activity timelines and score explanations
  • Search leads by metadata (company, industry, etc.)
  • Get top-performing leads
  • Retrieve segment information
  • Analyze engagement patterns

Example Queries​

"Show me the top 10 leads by score"
"Get details for lead ID abc-123"
"Find all leads from the Technology industry"
"Explain why lead abc-123 has their current score"
"What are our most engaged leads this week?"

Quick Setup​

  1. Navigate to the MCP Server directory:

    cd mcp-servers/lead-intelligence
    npm install
    npm run build

  2. Get API Credentials:

    • Go to Settings → Integrations in LeadVibe
    • Click Create API Secret
    • Copy your client_id and client_secret

API Secrets page showing the Create Credential form with ingest URL, credential name input, and a table of existing credentials with name, client ID, and creation date

  1. Create Configuration File:

    cp .env.example .env

    Edit .env:

    LEADVIBE_API_URL=https://your-leadvibe-instance.com
    LEADVIBE_CLIENT_ID=your-client-id
    LEADVIBE_CLIENT_SECRET=your-client-secret

  2. Configure Your AI Assistant:

    For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

    {
      "mcpServers": {
        "leadvibe": {
          "command": "node",
          "args": ["/absolute/path/to/mcp-servers/lead-intelligence/dist/index.js"],
          "env": {
            "LEADVIBE_API_URL": "https://your-leadvibe-instance.com",
            "LEADVIBE_CLIENT_ID": "your-client-id",
            "LEADVIBE_CLIENT_SECRET": "your-client-secret"
          }
        }
      }
    }

  3. Test the Connection:

    • Restart your AI assistant
    • Ask: "What lead tools do you have access to?"
    • You should see 10 LeadVibe tools listed

Available Tools​

The MCP Server provides these tools:

ToolDescription
get_leadGet complete lead details including scores and aliases
list_leadsList leads with filtering and pagination
get_lead_scoreGet score breakdown across all rulesets
get_lead_activityFetch complete activity timeline
get_score_explanationDetailed breakdown of how a lead earned their score
get_lead_eventsGet events with filtering by type
list_segmentsList all available segments
get_top_leadsGet highest-scoring leads
search_leads_by_metadataSearch by profile or account metadata
get_lead_metadataGet profile or account metadata for a lead

Authentication​

The MCP Server supports two authentication methods:

HTTP Basic Auth (Recommended)

  • Use organization secrets from Settings → Integrations
  • Long-lived credentials suitable for automation
  • Set LEADVIBE_CLIENT_ID and LEADVIBE_CLIENT_SECRET

Bearer Token (JWT)

  • Use Auth0/Clerk authentication tokens
  • Short-lived, user-specific access
  • Set LEADVIBE_AUTH_TOKEN

Organizational Unit Scoping​

All data access respects your organizational unit (OU) boundaries. To specify an OU:

LEADVIBE_OU_ID=your-ou-uuid

If not specified, the server uses the default OU for your organization.

Security Best Practices​

  • Never share API credentials - treat them like passwords
  • Rotate secrets regularly - create new secrets periodically
  • Use environment variables - never hardcode credentials
  • Restrict OU access - use role-based permissions to limit access
  • Monitor usage - check audit logs for unexpected activity

Troubleshooting​

Authentication Failed

  • Verify credentials in Settings → Integrations
  • Check that the API secret hasn't been deleted
  • Ensure LeadVibe API is accessible

Connection Errors

  • Verify LEADVIBE_API_URL is correct
  • Check network connectivity
  • Test with: curl https://your-instance.com/health

No Data Returned

  • Check OU permissions
  • Verify user has access to requested data
  • Review audit logs for access denials

Webhooks​

LeadVibe can send real-time notifications to external services when specific events occur.

Milestone Triggers​

Configure webhooks that fire when leads reach score thresholds:

  1. Go to Configure → Milestone Triggers
  2. Click Create Trigger
  3. Set threshold (e.g., 50 points)
  4. Add webhook URL
  5. Save

When a lead crosses the threshold, LeadVibe posts JSON data to your endpoint:

{
  "lead_id": "abc-123",
  "score": 52,
  "trigger_name": "Hot Lead Alert",
  "timestamp": "2025-01-15T10:30:00Z"
}

Webhook Security​

Webhooks include a signature header for verification:

X-LeadVibe-Signature: sha256=...

Verify the signature using your organization's webhook secret.

CRM Integrations​

Salesforce​

Connect LeadVibe to Salesforce to sync lead scores and activity:

  1. Create an Outbound Message or Flow
  2. POST to /ingest with lead data
  3. Use HTTP Basic Auth with your API credentials

HubSpot​

LeadVibe offers deep bidirectional integration with HubSpot, syncing contacts, engagement data, and lead scores automatically.

What Gets Synced​

From HubSpot to LeadVibe:

  • Contacts and their properties
  • Email engagement (opens, clicks)
  • Form submissions
  • Custom contact properties

From LeadVibe to HubSpot:

  • Lead engagement scores
  • Engagement level (as custom property)
  • Lead activity summaries
  • Segment memberships

Setup Instructions​

Prerequisites:

  • HubSpot account with API access
  • LeadVibe administrator access
  • Permission to create custom properties in HubSpot

Step 1: Create HubSpot Private App

  1. In HubSpot, go to Settings → Integrations → Private Apps
  2. Click Create a private app
  3. Name it "LeadVibe Integration"
  4. Under Scopes, enable:
    • crm.objects.contacts.read
    • crm.objects.contacts.write
    • crm.schemas.contacts.read
    • crm.schemas.contacts.write
  5. Click Create app
  6. Copy the Access Token

Step 2: Configure LeadVibe

  1. In LeadVibe, go to Settings → Integrations → HubSpot
  2. Click Connect HubSpot
  3. Paste your HubSpot Access Token
  4. Click Save Credentials

Govern Integrations HubSpot page showing the Configure HubSpot App instructions, Client ID and Client Secret input fields, and Save Credentials button

Step 3: Set Up Custom Properties (Optional)

LeadVibe can automatically create custom contact properties in HubSpot:

  1. Click Check Properties to see existing properties
  2. Click Setup Properties to create LeadVibe properties:
    • leadvibe_score (Number)
    • leadvibe_engagement_level (String)
    • leadvibe_last_activity (Date)
  3. Confirm property creation

Step 4: Configure Property Sync

Choose which HubSpot properties to sync to LeadVibe:

  1. Click Property Selection
  2. Select HubSpot contact properties to sync (e.g., firstname, lastname, company)
  3. Map to LeadVibe profile fields
  4. Click Save Selection

HubSpot integration configuration

Step 5: Test the Connection

  1. Click Test Connection
  2. Verify sync is working
  3. Check that test contact appears in LeadVibe

Bidirectional Sync Behavior​

Contact Sync (HubSpot → LeadVibe):

  • New HubSpot contacts create leads in LeadVibe
  • Contact property changes update lead profiles
  • Runs automatically every 15 minutes
  • Can be triggered manually via "Sync Now" button

Score Sync (LeadVibe → HubSpot):

  • Lead score updates push to HubSpot custom property
  • Engagement level updates push to HubSpot
  • Updates happen in real-time when scores change
  • Can be disabled per-trigger if desired

Event Sync (HubSpot → LeadVibe):

  • Email opens tracked via webhook
  • Email clicks tracked via webhook
  • Form submissions tracked via webhook
  • Custom events can be configured

Webhook Configuration​

LeadVibe listens for HubSpot webhooks:

Webhook URL: https://your-instance.com/integrations/hubspot/webhook

Supported Events:

  • contact.propertyChange
  • contact.creation
  • contact.deletion

Configure webhooks in HubSpot:

  1. Go to Settings → Integrations → Webhooks
  2. Create subscription for each event type
  3. Use the webhook URL above
  4. HubSpot will sign requests automatically

Sharing Leads and Segments​

Share Individual Lead:

  1. Open lead detail page
  2. Click Share to HubSpot
  3. Lead is created/updated in HubSpot with current score

Lead detail page with Share button

Share Segment:

  1. Go to Segments
  2. Click segment name
  3. Click Share to HubSpot
  4. All leads in segment are synced to HubSpot
  5. Optional: Create HubSpot list for the segment

Monitoring Sync Health​

View sync status and errors:

  1. Go to Settings → Integrations → HubSpot
  2. Check Sync Status section:
    • Last successful sync time
    • Number of contacts synced
    • Any recent errors

HubSpot integration settings

Sync Errors page shows:

  • Failed sync attempts
  • Error messages
  • Affected contact IDs
  • Retry options

Backfilling Historical Data​

Import existing HubSpot contacts:

  1. Go to Settings → Integrations → HubSpot
  2. Click Backfill Contacts
  3. Choose date range or "All contacts"
  4. Click Start Backfill
  5. Monitor progress in background

Note: Large backfills (10,000+ contacts) may take several hours.

Troubleshooting​

Connection Failed:

  • Verify Access Token is correct
  • Check HubSpot app scopes include required permissions
  • Ensure app is not suspended

Contacts Not Syncing:

  • Check sync filter settings (may exclude some contacts)
  • Verify sync is enabled (not paused)
  • Review sync errors for specific failures
  • Check API rate limits haven't been exceeded

Scores Not Updating in HubSpot:

  • Verify custom properties were created
  • Check property names match exactly
  • Ensure HubSpot app has write permissions
  • Review recent API errors

Webhook Events Not Received:

  • Verify webhook URL is accessible from HubSpot
  • Check webhook subscriptions are active
  • Review webhook signature validation
  • Check LeadVibe ingest failures log

API Rate Limits​

HubSpot enforces API rate limits:

  • Standard: 100 requests per 10 seconds
  • Bursts handled via queuing
  • LeadVibe automatically retries on rate limit errors

If you experience rate limit issues:

  • Reduce sync frequency
  • Stagger large operations
  • Contact HubSpot to increase limits

Zapier​

Connect LeadVibe to 5,000+ apps via Zapier:

  1. Set up milestone trigger with webhook URL
  2. Use Zapier's "Webhooks by Zapier" trigger
  3. Connect to any Zapier-supported app
  4. Build automated workflows

Slack Integration​

Send rich lead alerts directly to Slack channels or users. Slack integration provides real-time notifications when leads reach score milestones or complete important behavioral sequences.

Setup Instructions​

Step 1: Configure Slack App (Organization Admin)

  1. Go to Settings → Integrations → Slack
  2. Click Create Slack App or contact support for app credentials
  3. Enter your Slack app Client ID and Client Secret
  4. Click Save

Step 2: Connect Your Workspace (Per Organizational Unit)

  1. Go to Settings → Integrations → Slack
  2. Click Connect to Slack
  3. Select your Slack workspace
  4. Authorize LeadVibe to access:
    • Post to channels
    • Send direct messages
    • Read channel list
    • Read user list
  5. Choose default notification channel
  6. Click Allow

Slack integration settings page showing connected status, workspace name, bot user ID, last updated timestamp, Disconnect button, and default notification target with channel selector and Send Test Notification button

Step 3: Test Connection

  1. Click Send Test Notification
  2. Verify message appears in default channel
  3. Connection is ready to use

Notification Features​

Slack notifications include:

Lead Information:

  • Lead name or primary identifier (email, phone, etc.)
  • Current engagement score
  • Engagement level (e.g., "High", "Medium")

Score Breakdown (NEW):

  • Top 3 activities from last 24 hours
  • Activity counts and point values
  • Format: ✓ Event Type (count × points) +total
  • Example: ✓ page_view (5× @ 10 pts) +50

Interactive Actions:

  • View Lead button - Opens lead in LeadVibe
  • Assign to Me button - Claims the lead
  • View in HubSpot button (if HubSpot connected)

Example Notification:

🔥 Hot Lead Alert

Lead: jane.doe@example.com
Score: 75 points
Level: High Engagement

Recent Activity (24h):
✓ page_view (5× @ 10 pts) +50
✓ email_open (3× @ 5 pts) +15
✓ form_submit (1× @ 20 pts) +20

[View Lead] [Assign to Me]

Notification Routing​

Send to Channels:

  • Public channels (LeadVibe bot must be invited)
  • Private channels (bot must be invited)
  • Multiple channels per trigger supported

Send to Users:

  • Direct message to specific user
  • Round-robin assignment
  • Based on lead owner or territory

Default Target:

  • Set default channel/user per OU
  • Used when trigger doesn't specify target
  • Can be overridden per trigger

Configuring Triggers for Slack​

When creating Milestone or Sequence Triggers:

  1. Enable Send to Slack
  2. Choose Channel or User
  3. Select from dropdown:
    • Channels: Shows all accessible channels
    • Users: Shows workspace members
  4. Optional: Add custom message
  5. Save trigger

Trigger creation form with notification configuration

Example Configuration:

  • Trigger: Lead reaches 50 points
  • Send to: #sales-hot-leads channel
  • Custom message: "New qualified lead ready for outreach"

Managing Slack Connection​

Disconnect Slack:

  1. Go to Settings → Integrations → Slack
  2. Click Disconnect
  3. Confirms and removes workspace connection
  4. Existing triggers will stop sending notifications

Reconnect:

  • Follow the connection steps again
  • Previous trigger configurations are preserved
  • Channel/user selections may need updating if changed

Update Default Channel:

  1. Click Change Default Target
  2. Select new channel or user
  3. Click Save

Troubleshooting​

Connection Failed:

  • Verify Slack app credentials are correct
  • Check workspace permissions
  • Ensure you have admin access
  • Try disconnecting and reconnecting

Notifications Not Appearing:

  • Verify channel still exists
  • Check that LeadVibe bot is in the channel (invite it: /invite @LeadVibe)
  • Verify user hasn't blocked the bot
  • Check trigger is enabled
  • Review recent errors in Slack health dashboard

"Channel Not Found" Error:

  • Channel may have been deleted or renamed
  • Update trigger with new channel
  • Invite LeadVibe bot to private channels

Bot Not Responding to Buttons:

  • Verify Slack app has interactive components enabled
  • Check request URL is configured correctly
  • Ensure webhook signature validation passes
  • Review Slack app event subscriptions

Slack Health Dashboard​

Monitor Slack integration health:

  1. Go to Settings → Integrations → Slack
  2. View Health section:
    • Connection status
    • Last successful notification
    • Failed notification count
    • Recent errors

Slack integration status

Health Indicators:

  • 🟢 Green: All systems working
  • 🟡 Yellow: Minor issues detected
  • 🔴 Red: Connection problems

Microsoft Teams Integration​

Send lead alerts to Microsoft Teams channels and users. Teams integration provides the same rich notifications as Slack with support for Microsoft 365 environments.

Setup Instructions​

Step 1: Configure Teams App (Organization Admin)

  1. Go to Settings → Integrations → Microsoft Teams
  2. Click Create Teams App or contact support
  3. Enter your Teams app Client ID and Client Secret
  4. Click Save

Step 2: Connect Your Workspace (Per Organizational Unit)

  1. Go to Settings → Integrations → Teams
  2. Click Connect to Teams
  3. Sign in with Microsoft 365 account
  4. Authorize LeadVibe to:
    • Send messages to channels
    • Send direct chats
    • Read channel list
    • Read user list
  5. Choose default notification channel
  6. Click Accept

Govern Integrations Teams page showing connection status, Webhook URL input field, optional Channel Name field, and Connect button

Step 3: Test Connection

  1. Click Send Test Notification
  2. Verify message appears in default channel
  3. Connection is ready to use

Notification Features​

Teams notifications include the same information as Slack:

Adaptive Cards:

  • Rich formatting with images and buttons
  • Collapsible score breakdown section
  • Color-coded based on engagement level

Lead Information:

  • Lead name and identifier
  • Current score and level
  • Score breakdown

Interactive Actions:

  • View Lead - Opens in LeadVibe
  • Assign to Me - Claims lead
  • View in HubSpot (if connected)

Webhook-Based Notifications​

Teams also supports webhook-based notifications for simpler setup:

Step 1: Create Incoming Webhook in Teams

  1. In Teams, go to desired channel
  2. Click ⋯ (More options) → Connectors
  3. Find Incoming Webhook, click Configure
  4. Name it "LeadVibe Notifications"
  5. Copy the Webhook URL

Step 2: Configure in LeadVibe

  1. When creating a trigger, enable Teams Webhook
  2. Paste the webhook URL
  3. Save trigger

Note: Webhook notifications don't support interactive buttons but are simpler to set up.

Notification Routing​

Same options as Slack:

  • Send to channels (standard or private)
  • Send to users via direct chat
  • Set default targets per OU
  • Override per trigger

Troubleshooting​

Connection Failed:

  • Verify Microsoft 365 admin approved the app
  • Check app credentials are correct
  • Ensure Teams is enabled for your tenant
  • Try disconnecting and reconnecting

Notifications Not Appearing:

  • Verify channel exists and LeadVibe app is added
  • Check user hasn't blocked the app
  • Verify trigger is enabled
  • Review Teams health dashboard

Webhook Not Working:

  • Verify webhook URL is correct
  • Check webhook hasn't been deleted in Teams
  • Ensure webhook URL hasn't expired
  • Test with manual POST request

Adaptive Cards Not Rendering:

  • Teams may be caching old card format
  • Clear Teams cache and restart
  • Verify card JSON is valid
  • Check Teams desktop/mobile version

Teams Health Dashboard​

Monitor Teams integration:

  1. Go to Settings → Integrations → Teams
  2. View Health section:
    • Connection status
    • Last successful notification
    • Failed notification count
    • Recent errors

API Access​

For custom integrations, use the LeadVibe REST API:

Base URL: https://your-instance.com/api

Authentication: HTTP Basic Auth or Bearer token

Key Endpoints:

  • POST /ingest - Send engagement events
  • GET /leads - List leads
  • GET /score/\{leadID\} - Get lead score
  • GET /events - Query events

Full API Reference: See OpenAPI Documentation

Need Help?​

  • MCP Server Issues: Check mcp-servers/lead-intelligence/README.md
  • API Questions: Review the OpenAPI spec
  • Webhook Setup: Contact support for debugging assistance
  • General Help: Use the Help menu in the app