Everyday Workflows Client Portal

HubSpot-Integration-Technical-Spec

8 min read

HubSpot Integration Technical Specification

NeuroPathway → HubSpot Real-Time Sync

Non-Contract Document

This technical specification is provided for implementation and testing guidance only. In the event of any conflict, the executed Change Order governs scope, acceptance, warranty, payment terms, and deliverables.

Project: HubSpot Integration for NeuroPathway Scheduling Platform Client: Neuro Pathway LLC Developer: Alex De Gracia (Everyday Workflows) Document Version: 1.1 Date: December 15, 2025

📋 Executive Overview

Integration Type

One-way, real-time synchronization from NeuroPathway platform to HubSpot CRM Contacts object.

Data Flow

NeuroPathway Platform → Webhook → HubSpot API → HubSpot Contacts
                                    ↓
                            Database Sync (Initial Migration)

Scope Summary

  • 4 Custom Fields in HubSpot Contacts
  • Outlook-compatible calendar meeting invites (Accept/Decline experience)
  • Real-time Webhooks for live updates
  • Initial Data Migration/Backfill for existing records
  • Email-based Record Matching for Contact identification

🎯 Field Specifications

HubSpot Contact Fields to Create

Field NameData TypeRequiredPurposeSource
interview_statusStringNoCurrent scheduling statusNeuroPathway DB
interview_scheduling_urlURLNoCandidate invitation URLNeuroPathway DB
recent_candidate_conversion_pageStringYes*Job number + custom textForm input + NeuroPathway
interview_scheduled_atDateTimeNoScheduled interview date/timen8n (Zoom meeting) → NeuroPathway DB

*Required for new records created after integration deployment

Data Mapping

1. interview_status

  • Source: scheduling_status field in NeuroPathway database
  • Format: String (existing values preserved)
  • Sync Trigger: Any status change in NeuroPathway
  • Initial Migration: All existing records with status values

2. interview_scheduling_url

  • Source: invitation_url field in NeuroPathway database
  • Format: Full URL string
  • Sync Trigger: URL generation or update in NeuroPathway
  • Initial Migration: All existing records with URL values

3. recent_candidate_conversion_page

  • Source: Combination of:
    • Job number (manually entered in NeuroPathway UI)
    • Custom text string (from interview creation form)
  • Format: ${job_number}:${custom_text}
  • Sync Trigger: Form submission in NeuroPathway
  • Initial Migration: Not applicable (new field)

4. interview_scheduled_at

  • Source: Scheduled meeting start time produced by the n8n automation (Zoom meeting creation)
  • Storage: Persisted to NeuroPathway DB when the interview is scheduled
  • Format: ISO timestamp (UTC) mapped to HubSpot DateTime property
  • Sync Trigger: When a pair transitions to scheduled / meeting details are created
  • Initial Migration/Backfill: Populate for historical pairs where a scheduled meeting exists

📅 Calendar Invite Upgrade (Outlook-Compatible)

Objective

Replace the current “download/open the .ics file” experience with a true meeting invitation email so recipients can Accept/Decline directly in Outlook (desktop/web/mobile).

Approach (High-Level)

  • Generate an iCalendar meeting request (METHOD:REQUEST) that includes organizer + attendee list.
  • Send the invite email automatically to candidate, hiring partner, and any additional guests when the interview is scheduled.
  • The invite should display as a standard calendar invitation (not a generic attachment download).

Scope Boundary

This is an Outlook-compatible invite delivery upgrade (meeting request formatting). Full Microsoft 365 tenant integration (Graph-based calendar writes) is out of scope unless separately approved.

🔧 Technical Architecture

Integration Components

1. Webhook System

NeuroPathway Event → Webhook Endpoint → Validation → HubSpot API → Update
                     ↓
                Logging & Error Handling

2. Database Sync Engine

NeuroPathway DB → Query All Records → Email Matching → Batch Update HubSpot
                        ↓
                   Progress Tracking

3. Form Modification

Interview Creation Form → Add Conversion Field → Validation → Store in DB
                                ↓
                           Trigger Real-time Sync

API Requirements

HubSpot API Endpoints Needed

  • Contacts API: POST /crm/v3/objects/contacts/{contactId}
  • Search API: POST /crm/v3/objects/contacts/search (for email matching)
  • Private App Authentication: Bearer token required

Required HubSpot Scopes

  • contacts (read/write)
  • crm.objects.contacts.read
  • crm.objects.contacts.write

🗓️ Development Phases

Phase 1: Setup & Configuration (2-3 hours)

Deliverables:

  • HubSpot private app setup with proper scopes
  • API credentials and authentication testing
  • Field creation in HubSpot Contacts object
  • Initial database schema review

Client Dependencies:

  • Ron provides HubSpot private app credentials
  • Client confirms field structure and values

Phase 2: Core Development (8-12 hours)

Deliverables:

  • Form Modification:
    • Add “recent_candidate_conversion_page” input field
    • Frontend: HTML form field + validation
    • Backend: Database schema update + validation logic
  • Webhook Implementation:
    • Webhook endpoint creation
    • Event detection for all four fields
    • HubSpot API integration
  • Database Migration:
    • Script to sync existing interview_status data
    • Script to sync existing interview_scheduling_url data
    • Email-based contact matching algorithm

Key Technical Tasks:

// Email matching algorithm
function findHubSpotContact(email) {
  return hubspotClient.crm.contacts.searchApi.doSearch({
    filterGroups: [{
      filters: [{
        propertyName: 'email',
        operator: 'EQ',
        value: email
      }]
    }]
  });
}
 
// Webhook handler
function handleWebhook(event) {
  const { contactId, fieldName, newValue } = event.data;
 
  switch(fieldName) {
    case 'interview_status':
    case 'interview_scheduling_url':
    case 'recent_candidate_conversion_page':
    case 'interview_scheduled_at':
      updateHubSpotContact(contactId, fieldName, newValue);
      break;
  }
}

Phase 3: Testing & Deployment (4-6 hours)

Deliverables:

  • Staging Environment Testing:
    • Webhook trigger validation
    • Data sync accuracy verification
    • Error handling testing
    • Rate limiting compliance
  • Production Deployment:
    • Initial data migration execution
    • Webhook activation
    • Monitoring setup
  • Documentation:
    • Technical maintenance guide
    • Troubleshooting procedures
    • API rate limiting guidelines

🧪 Testing Requirements

Test Cases

0. Calendar Invite Testing (Outlook-Compatible)

  • When a match is scheduled, recipients receive an invite with Accept/Decline controls (Outlook)
  • Invite includes correct date/time + timezone and Zoom join link
  • All participants are included (candidate, hiring partner, guests)

1. Webhook Testing

  • Status change triggers webhook
  • URL update triggers webhook
  • Form submission triggers webhook
  • Scheduled-at update triggers webhook
  • Multiple rapid updates handled correctly
  • Invalid data rejected appropriately

2. Data Migration Testing

  • All existing contacts matched by email
  • Status values transferred correctly
  • URL values transferred correctly
  • Unmatched contacts logged for manual review
  • Migration progress tracked and resumable

3. Integration Testing

  • Real-time sync <1 minute delay
  • Error handling for invalid emails
  • Rate limiting compliance (100 requests/10 seconds)
  • Duplicate record prevention
  • Data consistency maintained

Test Data

  • Sample Contacts: 10-20 test records with various status values
  • Test Scenarios: Happy path, edge cases, error conditions
  • Performance Testing: Load testing with 100+ concurrent updates

🚀 Deployment Checklist

Pre-Deployment

  • HubSpot private app configured with correct scopes
  • All four custom fields created in HubSpot Contacts
  • Webhook endpoint tested and validated
  • Database migration scripts tested on staging data
  • Error logging and monitoring configured

Deployment Steps

  1. Create HubSpot Fields (Client responsibility - Ron)
  2. Deploy Webhook Code to production environment
  3. Execute Data Migration during low-traffic period
  4. Activate Webhooks in NeuroPathway platform
  5. Verify Integration with test data
  6. Monitor Initial Performance for 24-48 hours

Post-Deployment

  • Confirm real-time sync working
  • Verify data accuracy for all four fields
  • Check error logs for any issues
  • Document any manual interventions required
  • Create monitoring alerts for failures

📊 Performance & Monitoring

Performance Targets

  • Sync Latency: <1 minute for real-time updates
  • Data Accuracy: 100% for email-matched contacts
  • API Rate Compliance: Stay within HubSpot limits (100 req/10sec)
  • Error Rate: <1% of total syncs

Monitoring Requirements

  • Webhook Success/Failure Rates
  • API Response Times
  • Data Migration Progress
  • Error Log Analysis
  • Contact Match Rates

Alert Conditions

  • Webhook failure rate >5%
  • API response time >30 seconds
  • Data migration stuck for >1 hour
  • Contact match rate <95%

🔒 Security & Compliance

Data Security

  • API Keys: Store in environment variables, never in code
  • Data Encryption: HTTPS for all API communications
  • Access Control: Limit webhook endpoint access by IP if possible
  • Audit Trail: Log all data changes with timestamps

Privacy Considerations

  • Email Matching: Use only for contact identification
  • Data Retention: Follow HubSpot’s data retention policies
  • User Consent: Ensure client has proper consent for data transfer
  • GDPR Compliance: Document data flow for compliance review

🛠️ Maintenance & Support

30-Day Warranty Coverage

  • Critical Bugs: Fix within 24 hours
  • Data Sync Issues: Investigate and resolve within 48 hours
  • API Integration Problems: Troubleshoot and repair within 72 hours
  • Performance Issues: Optimize and improve within 1 week

Post-Warranty Support

  • Bug Fixes: Available under monthly retainer
  • Feature Enhancements: Separate change order required
  • HubSpot API Changes: Monitoring and adaptation as needed
  • Performance Optimization: Available upon request

Documentation Deliverables

  1. Technical Architecture Diagram
  2. API Integration Guide
  3. Webhook Troubleshooting Guide
  4. Data Migration Report
  5. Maintenance Procedures

⚠️ Risk Mitigation

Technical Risks

RiskProbabilityImpactMitigation
HubSpot API changesLowMediumMonitor API changes, use versioned endpoints
Email matching failuresMediumHighImplement fallback matching strategies
Rate limiting issuesMediumMediumImplement proper throttling and queuing
Data inconsistencyLowHighComprehensive testing and validation

Business Risks

  • Scope Creep: Fixed fee covers only four specified fields
  • Timeline Delays: Dependencies on client credential delivery
  • Data Quality: Migration assumes “as-is” data quality
  • User Adoption: Form field addition may require user training

📞 Support Contacts

Technical Support

  • Primary: Alex De Gracia (alex@everydayworkflows.com)
  • Backup: [Developer contact if applicable]
  • Response Time: 24-48 hours for non-critical issues

Client Contacts

  • Technical: Ron Berry III (HubSpot configuration)
  • Business: Zack Mandler (Project approval)
  • End User: Scott (Form usage and testing)

📝 Implementation Notes

Key Technical Decisions

  1. All fields sync to Contacts object (simplified from original Jobs plan)
  2. Email-based matching for contact identification
  3. Webhook-based real-time sync for immediate updates
  4. Batch migration for existing data population
  5. Fixed field names to prevent configuration drift

Development Priorities

  1. Form modification (user-facing impact)
  2. Webhook implementation (core functionality)
  3. Data migration (data completeness)
  4. Testing and validation (quality assurance)
  5. Documentation (maintainability)

Success Metrics

  • Technical: All four fields sync correctly and reliably (interview_status, interview_scheduling_url, recent_candidate_conversion_page, interview_scheduled_at)
  • Business: Client can track scheduling + interview dates in HubSpot
  • Performance: Real-time updates under 1 minute
  • Quality: Zero data loss during migration and sync

Document Status: Ready for Development Next Step: Begin Phase 1 - Setup & Configuration Estimated Completion: January 31, 2026 (or sooner)

Graph View