flowchart LR
    A[HubSpot Contact Update] --> B[HubSpot Webhook]
    B --> C[Your Server /webhook/hubspot]
    C --> D[Validation & Deduplication]
    D --> E[Queue Job]
    E --> F[Salesforce REST API Upsert]
    F --> G[Update HubSpot with Salesforce ID]
    G --> H[Log Success/Failure]

// Server setup - Express with webhook validation
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

const HUBSPOT_CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
const SALESFORCE_INSTANCE_URL = process.env.SALESFORCE_INSTANCE_URL;
const SALESFORCE_ACCESS_TOKEN = process.env.SALESFORCE_ACCESS_TOKEN;

// Webhook signature validation - prevents replay attacks
function validateHubSpotSignature(req) {
  const signature = req.headers['x-hubspot-signature-v3'];
  const requestBody = JSON.stringify(req.body);
  const timestamp = req.headers['x-hubspot-request-timestamp'];
  
  const sourceString = `v3:${timestamp}:${requestBody}`;
  const hash = crypto.createHmac('sha256', HUBSPOT_CLIENT_SECRET)
    .update(sourceString)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hash)
  );
}

// Salesforce OAuth token refresh
async function refreshSalesforceToken() {
  const response = await fetch('https://login.salesforce.com/services/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: process.env.SALESFORCE_CLIENT_ID,
      client_secret: process.env.SALESFORCE_CLIENT_SECRET,
      refresh_token: process.env.SALESFORCE_REFRESH_TOKEN
    })
  });
  
  if (!response.ok) {
    throw new Error(`OAuth refresh failed: ${response.status}`);
  }
  
  const data = await response.json();
  return data.access_token;
}

const processedEvents = new Set(); // Use Redis in production

app.post('/webhook/hubspot', async (req, res) => {
  // Validate signature first - reject invalid requests immediately
  if (!validateHubSpotSignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Respond fast - HubSpot times out after 5 seconds
  res.status(200).send('Received');
  
  // Process async to avoid webhook timeout
  const events = req.body;
  
  for (const event of events) {
    const eventId = `${event.objectId}_${event.occurredAt}`;
    
    // Deduplication check
    if (processedEvents.has(eventId)) {
      console.log(`Skipping duplicate event: ${eventId}`);
      continue;
    }
    
    processedEvents.add(eventId);
    
    try {
      await syncToSalesforce(event);
    } catch (error) {
      console.error(`Sync failed for ${eventId}:`, error);
      // Implement retry queue here
    }
  }
});

async function syncToSalesforce(event) {
  const hubspotContactId = event.objectId;
  
  // Fetch full contact data from HubSpot
  const contactResponse = await fetch(
    `https://api.hubapi.com/crm/v3/objects/contacts/${hubspotContactId}?properties=email,firstname,lastname,phone`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.HUBSPOT_API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!contactResponse.ok) {
    throw new Error(`HubSpot API error: ${contactResponse.status}`);
  }
  
  const contact = await contactResponse.json();
  
  // Salesforce upsert using external ID field
  const salesforcePayload = {
    Email: contact.properties.email,
    FirstName: contact.properties.firstname,
    LastName: contact.properties.lastname,
    Phone: contact.properties.phone,
    HubSpot_Contact_ID__c: hubspotContactId // Custom external ID field
  };
  
  const upsertResponse = await fetch(
    `${SALESFORCE_INSTANCE_URL}/services/data/v58.0/sobjects/Contact/HubSpot_Contact_ID__c/${hubspotContactId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${SALESFORCE_ACCESS_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(salesforcePayload)
    }
  );
  
  if (!upsertResponse.ok) {
    const error = await upsertResponse.json();
    throw new Error(`Salesforce upsert failed: ${JSON.stringify(error)}`);
  }
  
  console.log(`Synced contact ${hubspotContactId} to Salesforce`);
}

async function upsertWithRetry(url, payload, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url, {
        method: 'PATCH',
        headers: {
          'Authorization': `Bearer ${SALESFORCE_ACCESS_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
      });
      
      if (response.status === 429) {
        const waitTime = Math.pow(2, i) * 1000; // Exponential backoff
        console.log(`Rate limited. Retrying in ${waitTime}ms`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${await response.text()}`);
      }
      
      return await response.json();
    } catch (error) {
      if (i === retries - 1) throw error;
    }
  }
}

sequenceDiagram
    participant Client
    participant HubSpotAPI
    participant WebhookService
    participant CRM
    participant ErrorHandler

    Client->>HubSpotAPI: Create Contact
    HubSpotAPI->>CRM: { contactData }
    CRM-->>HubSpotAPI: { contactId, status: "created" }
    HubSpotAPI->>WebhookService: Trigger Webhook
    WebhookService->>Client: { event: "contact.created", contactId }

    Client->>HubSpotAPI: Update Contact
    HubSpotAPI->>CRM: { contactId, updatedData }
    CRM-->>HubSpotAPI: { status: "updated" }
    HubSpotAPI->>WebhookService: Trigger Webhook
    WebhookService->>Client: { event: "contact.updated", contactId }

    Client->>HubSpotAPI: Delete Contact
    HubSpotAPI->>CRM: { contactId }
    CRM-->>HubSpotAPI: { status: "deleted" }
    HubSpotAPI->>WebhookService: Trigger Webhook
    WebhookService->>Client: { event: "contact.deleted", contactId }

    Client->>HubSpotAPI: Invalid Request
    HubSpotAPI->>ErrorHandler: { error: "invalid_request" }
    ErrorHandler->>Client: { errorMessage: "Invalid request format" }

// Start ngrok tunnel (terminal)
// ngrok http 3000

// Test webhook signature validation locally
const testPayload = {
  objectId: 12345,
  propertyName: "email",
  propertyValue: "test@example.com",
  changeSource: "CRM",
  eventId: 1,
  subscriptionId: 67890,
  portalId: 123456,
  occurredAt: Date.now()
};

const testSignature = crypto
  .createHmac('sha256', HUBSPOT_CLIENT_SECRET)
  .update(JSON.stringify(testPayload))
  .digest('hex');

// Send test request with curl
// curl -X POST http://localhost:3000/webhook/hubspot \
//   -H "Content-Type: application/json" \
//   -H "X-HubSpot-Signature: sha256=YOUR_SIGNATURE_HERE" \
//   -d '{"objectId":12345,"propertyName":"email"}'

// Verify signature validation fires
app.post('/webhook/hubspot', (req, res) => {
  const signature = req.headers['x-hubspot-signature'];
  if (!validateHubSpotSignature(signature, req.body)) {
    console.error('Signature validation failed'); // Should log on bad signature
    return res.status(401).send('Unauthorized');
  }
  console.log('Signature valid, processing event'); // Should log on success
  res.status(200).send('OK');
});

// Validate webhook receives events (check server logs)
// 1. Update a contact in HubSpot UI
// 2. Check your server logs for incoming POST to /webhook/hubspot
// 3. Verify eventId is logged and not reprocessed

// Test deduplication logic
const testDuplicateEvent = async () => {
  const eventId = 999;
  processedEvents.add(eventId); // Simulate already processed
  
  // This should be rejected
  if (processedEvents.has(eventId)) {
    console.log('Duplicate event blocked correctly'); // Expected output
    return;
  }
  
  console.error('Deduplication failed - event processed twice'); // Should NOT log
};

// Verify Salesforce REST API upsert works
// Check Salesforce UI for synced contact after HubSpot update
// Response should be 200/201 with Salesforce record ID

// Event 1: Email change (timestamp: 1703001234567)
{
  "eventId": "evt_abc123",
  "subscriptionId": 12345,
  "portalId": 98765,
  "objectId": 401,
  "propertyName": "email",
  "propertyValue": "new@example.com",
  "changeSource": "CRM_UI",
  "occurredAt": 1703001234567
}

// Event 2: Phone change (timestamp: 1703001234612) - 45ms later
{
  "eventId": "evt_abc124",
  "subscriptionId": 12345,
  "portalId": 98765,
  "objectId": 401, // SAME contact
  "propertyName": "phone",
  "propertyValue": "+1234567890",
  "changeSource": "CRM_UI",
  "occurredAt": 1703001234612
}

// Production deduplication with time-based cleanup
const processedEvents = new Map(); // eventId → timestamp

app.post('/webhook/hubspot', async (req, res) => {
  const events = Array.isArray(req.body) ? req.body : [req.body];
  
  for (const event of events) {
    const { eventId, objectId, occurredAt } = event;
    
    // Deduplicate by objectId within 5-second window
    const recentEvent = processedEvents.get(objectId);
    if (recentEvent && (occurredAt - recentEvent) < 5000) {
      console.log(`Skipping duplicate event for contact ${objectId}`);
      continue; // Skip this event
    }
    
    processedEvents.set(objectId, occurredAt);
    
    // Validate signature using exact function name from symbol table
    if (!validateHubSpotSignature(req.body, req.headers['x-hubspot-signature'])) {
      return res.status(401).send('Invalid signature');
    }
    
    await syncToSalesforce(objectId); // Process once per contact
  }
  
  res.status(200).send('OK');
});

// Cleanup old entries every 10 seconds to prevent memory leak
setInterval(() => {
  const now = Date.now();
  for (const [objectId, timestamp] of processedEvents.entries()) {
    if (now - timestamp > 10000) processedEvents.delete(objectId);
  }
}, 10000);

// WRONG: Body already parsed as JSON
app.post('/webhook/hubspot', express.json(), (req, res) => {
  const sourceString = req.body.method + req.body.requestBody + timestamp; // FAILS
});

// CORRECT: Access raw buffer before parsing
app.post('/webhook/hubspot', express.raw({ type: 'application/json' }), (req, res) => {
  const requestBody = req.body.toString('utf8'); // Raw bytes → string
  const timestamp = req.headers['x-hubspot-request-timestamp'];
  const sourceString = req.method + requestBody + timestamp;
  const hash = crypto.createHmac('sha256', HUBSPOT_CLIENT_SECRET).update(sourceString).digest('hex');
  
  if (hash !== req.headers['x-hubspot-signature']) {
    return res.status(401).send('Invalid signature');
  }
  // Process webhook...
});

// Add mutex lock to prevent concurrent upserts for same contact
const upsertLocks = new Map();

async function upsertWithRetry(salesforcePayload, hubspotContactId) {
  if (upsertLocks.has(hubspotContactId)) {
    console.log(`Upsert already in progress for ${hubspotContactId}, skipping`);
    return;
  }
  
  upsertLocks.set(hubspotContactId, true);
  
  try {
    const response = await fetch(`${SALESFORCE_INSTANCE_URL}/services/data/v58.0/sobjects/Contact/Email__c/${salesforcePayload.Email}`, {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${SALESFORCE_ACCESS_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(salesforcePayload)
    });
    
    if (response.status === 401) await refreshSalesforceToken();
  } finally {
    upsertLocks.delete(hubspotContactId); // Release lock
  }
}

const processedEvents = new Map(); // eventId → timestamp

events.forEach(event => {
  const eventId = event.eventId;
  const now = Date.now();
  
  // Check if processed in last 2 minutes (120000ms)
  const recentEvent = processedEvents.get(eventId);
  if (recentEvent && (now - recentEvent) < 120000) {
    console.log(`Duplicate event ${eventId} within 2min window, skipping`);
    return;
  }
  
  processedEvents.set(eventId, now);
  syncToSalesforce(event);
});

// server.js - Production HubSpot → Salesforce webhook bridge
const express = require('express');
const crypto = require('crypto');
const fetch = require('node-fetch');

const app = express();
app.use(express.json());

// Environment variables (set these in production)
const HUBSPOT_CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
const SALESFORCE_INSTANCE_URL = process.env.SALESFORCE_INSTANCE_URL; // e.g., https://yourinstance.salesforce.com
const SALESFORCE_ACCESS_TOKEN = process.env.SALESFORCE_ACCESS_TOKEN; // Refresh this token periodically
const SALESFORCE_REFRESH_TOKEN = process.env.SALESFORCE_REFRESH_TOKEN;
const SALESFORCE_CLIENT_ID = process.env.SALESFORCE_CLIENT_ID;
const SALESFORCE_CLIENT_SECRET = process.env.SALESFORCE_CLIENT_SECRET;

// In-memory stores (use Redis in production)
const processedEvents = new Set();
const upsertLocks = new Map();

// Validate HubSpot webhook signature
function validateHubSpotSignature(signature, requestBody, timestamp) {
  const sourceString = HUBSPOT_CLIENT_SECRET + requestBody + timestamp;
  const hash = crypto.createHash('sha256').update(sourceString).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
}

// Refresh Salesforce OAuth token when expired
async function refreshSalesforceToken() {
  try {
    const response = await fetch('https://login.salesforce.com/services/oauth2/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: SALESFORCE_REFRESH_TOKEN,
        client_id: SALESFORCE_CLIENT_ID,
        client_secret: SALESFORCE_CLIENT_SECRET
      })
    });
    
    if (!response.ok) throw new Error(`Token refresh failed: ${response.status}`);
    const data = await response.json();
    process.env.SALESFORCE_ACCESS_TOKEN = data.access_token; // Update in-memory token
    return data.access_token;
  } catch (error) {
    console.error('Salesforce token refresh error:', error);
    throw error;
  }
}

// Sync HubSpot contact to Salesforce with retry logic
async function syncToSalesforce(hubspotContactId, properties) {
  // Prevent duplicate upserts for same contact
  if (upsertLocks.has(hubspotContactId)) {
    console.log(`Upsert already in progress for contact ${hubspotContactId}`);
    return;
  }
  
  upsertLocks.set(hubspotContactId, Date.now());
  
  try {
    // Fetch full contact data from HubSpot
    const contactResponse = await fetch(
      `https://api.hubapi.com/crm/v3/objects/contacts/${hubspotContactId}?properties=email,firstname,lastname,phone,company`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.HUBSPOT_ACCESS_TOKEN}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!contactResponse.ok) throw new Error(`HubSpot API error: ${contactResponse.status}`);
    const contact = await contactResponse.json();
    
    // Map HubSpot properties to Salesforce Contact object
    const salesforcePayload = {
      Email: contact.properties.email,
      FirstName: contact.properties.firstname || '',
      LastName: contact.properties.lastname || 'Unknown',
      Phone: contact.properties.phone || '',
      Company: contact.properties.company || '',
      HubSpot_Contact_ID__c: hubspotContactId // Custom field for tracking
    };
    
    // Upsert to Salesforce using Email as external ID
    const upsertResponse = await upsertWithRetry(salesforcePayload);
    console.log(`Synced contact ${hubspotContactId} to Salesforce:`, upsertResponse.id);
    
  } catch (error) {
    console.error(`Sync failed for contact ${hubspotContactId}:`, error);
    throw error;
  } finally {
    upsertLocks.delete(hubspotContactId);
  }
}

// Retry upsert with exponential backoff (handles 503, token expiry)
async function upsertWithRetry(salesforcePayload, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(
        `${SALESFORCE_INSTANCE_URL}/services/data/v58.0/sobjects/Contact/Email/${salesforcePayload.Email}`,
        {
          method: 'PATCH',
          headers: {
            'Authorization': `Bearer ${SALESFORCE_ACCESS_TOKEN}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(salesforcePayload)
        }
      );
      
      // Token expired - refresh and retry
      if (response.status === 401) {
        console.log('Salesforce token expired, refreshing...');
        await refreshSalesforceToken();
        continue;
      }
      
      // Rate limit or server error - exponential backoff
      if (response.status === 503 || response.status === 429) {
        const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        console.log(`Salesforce unavailable, retrying in ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      if (!response.ok) throw new Error(`Salesforce upsert failed: ${response.status}`);
      return await response.json();
      
    } catch (error) {
      if (i === retries - 1) throw error;
      console.log(`Retry ${i + 1}/${retries} after error:`, error.message);
    }
  }
}

// Webhook endpoint - receives HubSpot contact.propertyChange events
app.post('/webhook/hubspot', async (req, res) => {
  const signature = req.headers['x-hubspot-signature-v3'];
  const timestamp = req.headers['x-hubspot-request-timestamp'];
  const requestBody = JSON.stringify(req.body);
  
  // Validate webhook signature
  if (!validateHubSpotSignature(signature, requestBody, timestamp)) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Unauthorized');
  }
  
  // Respond immediately (HubSpot times out after 5s)
  res.status(200).send('OK');
  
  // Process events asynchronously
  const events = req.body;
  for (const event of events) {
    const eventId = `${event.objectId}_${event.propertyName}_${event.occurredAt}`;
    
    // Deduplicate events (HubSpot may send duplicates)
    if (processedEvents.has(eventId)) {
      console.log(`Skipping duplicate event: ${eventId}`);
      continue;
    }
    processedEvents.add(eventId);
    
    // Only sync contact property changes
    if (event.subscriptionType === 'contact.propertyChange') {
      try {
        await syncToSalesforce(event.objectId, event.propertyValue);
      } catch (error) {
        console.error(`

## FAQ

### Technical Questions

**How do I validate that webhooks are actually coming from HubSpot?**

HubSpot signs every webhook with an HMAC-SHA256 signature. You reconstruct the signature by concatenating the request body with your client secret, then comparing it to the `X-HubSpot-Request-Signature` header. The `validateHubSpotSignature` function checks this by hashing the sourceString (requestBody + timestamp + HUBSPOT_CLIENT_SECRET) and comparing it to the incoming signature. This prevents spoofed requests from hitting your endpoint. Skip this validation and attackers can trigger false syncs to Salesforce, corrupting your data.

**What's the difference between webhook subscriptions and polling?**

Webhooks fire immediately when an event occurs in HubSpot (contact created, property updated). Polling requires you to repeatedly query HubSpot's API at intervals, wasting API calls and introducing lag. Webhooks are event-driven; polling is time-driven. For real-time data synchronization, webhooks win on latency (sub-second vs. minutes) and cost (no wasted API calls). The tradeoff: webhooks require a publicly accessible server and retry logic for failed deliveries.

**How do I handle duplicate webhook events?**

HubSpot can deliver the same event multiple times due to network retries. Store the eventId and timestamp in a deduplication cache (Redis, in-memory map with TTL). Before processing, check if you've seen this eventId recently. If yes, skip it. The upsertLocks pattern prevents race conditions when the same contact is updated twice in rapid succession—lock the contact ID, process the first event, release the lock, then process the second.

**Why does my Salesforce upsert fail silently?**

Salesforce returns HTTP 200 even when individual records fail. You must parse the response array and check the `success` field for each record. If `success: false`, inspect the `errors` array for the actual reason (invalid field, permission denied, duplicate rule triggered). The upsertWithRetry function handles transient failures (503, 429) with exponential backoff, but permanent failures (400, 403) need manual investigation.

### Performance

**How much latency should I expect from HubSpot to Salesforce?**

Webhook delivery: 100-500ms. Token refresh (if needed): 200-800ms. Salesforce upsert: 300-1200ms depending on record complexity and org load. Total end-to-end: 500ms-2s. If you're syncing 10,000 contacts, don't do it synchronously—batch them with async processing and queue them with exponential backoff to avoid rate limits (Salesforce: 10,000 API calls per 24 hours for most orgs).

**What happens if my webhook endpoint goes down?**

HubSpot retries for 5 minutes with exponential backoff (1s, 2s, 4s, 8s, etc.). After that, the event is lost. Implement a dead-letter queue: if your endpoint returns non-2xx status, log the event to a database and replay it later. Monitor webhook failures in HubSpot's Activity Log (Settings → Integrations → Webhooks).

### Platform Comparison

**Should I use HubSpot's native Salesforce integration instead?**

HubSpot's native integration syncs contacts and companies bidirectionally but doesn't support custom objects or complex field mappings. Webhooks give you full control: sync any object, apply business logic, handle edge cases. Native integration is simpler but less flexible. Use webhooks if you need custom transformations or sync beyond standard contacts.

**Can I sync from Salesforce back to HubSpot?**

Yes, but it requires a separate flow. Salesforce webhooks (Platform Events or Outbound Messages) trigger your server, which calls HubSpot's API to update contacts. This creates bidirectional sync but introduces complexity: circular updates (A→B→A), conflicting timestamps, and deduplication across both directions. Most teams sync one direction (HubSpot → Salesforce) to avoid this mess.

## Resources

**HubSpot Webhooks Documentation**
Official guide for webhook subscriptions, event types, and signature validation. Reference for `HUBSPOT_CLIENT_SECRET` and payload structures used in real-time data synchronization.

**Salesforce REST API Reference**
Complete REST API documentation covering OAuth 2.0 token refresh, upsert operations, and `SALESFORCE_INSTANCE_URL` configuration for CRM record updates.

**GitHub: HubSpot-Salesforce Sync**
Production webhook handler implementation with `validateHubSpotSignature`, `refreshSalesforceToken`, and `upsertWithRetry` functions for event deduplication and error recovery.

**Webhook Security Best Practices**
OWASP guidance on signature validation, timestamp verification, and preventing replay attacks when processing HubSpot webhook events.

## References

1. https://developers.hubspot.com/docs/api/overview
2. https://developers.hubspot.com/docs/api/crm/contacts