GoHighLevel API v2 & Developer Ecosystem

Enterprise SDK & Webhook Middleware Architectures

Extracted directly from the official highlevel-api-sdk and ghl-marketplace-app-template repositories.

import HighLevel, { MongoDBSessionStorage, LogLevel } from '@gohighlevel/api-client';

// Initialize HighLevel SDK with persistent session storage and automatic 429 burst retry
const ghl = new HighLevel({
  clientId: process.env.GHL_CLIENT_ID,
  clientSecret: process.env.GHL_CLIENT_SECRET,
  sessionStorage: new MongoDBSessionStorage(
    process.env.MONGODB_URI,
    'ghl_enterprise_vault',
    'oauth_sessions'
  ),
  logLevel: LogLevel.INFO,
  rateLimitRetry: {
    maxRetries: 3,     // Automatically backs off and retries when X-RateLimit-Remaining is 0
    maxDelayMs: 10000, // Capped maximum wait interval per burst cycle
    baseDelayMs: 1000  // Exponential backoff base delay for responses missing headers
  }
});

// Programmatic Contact Upsert with Location Scoping
async function syncContact(locationId: string, email: string, customData: Record<string, any>) {
  const contact = await ghl.contacts.upsertContact({
    email,
    phone: customData.phone,
    name: customData.name,
    tags: ['Enterprise-API-Sync', 'SQL-Connected'],
    customFields: [
      { id: 'ext_account_id', value: customData.accountId },
      { id: 'lead_score', value: customData.score }
    ]
  }, { 
    headers: { locationId } 
  });

  return contact;
}

import express from 'express';
import HighLevel from '@gohighlevel/api-client';

const app = express();
const ghl = new HighLevel({
  webhookPublicKey: process.env.WEBHOOK_SIGNATURE_PUBLIC_KEY // Base64 or PEM Ed25519 public key
});

// Preserve raw body buffer for byte-level cryptographic signature verification
app.use(express.json({ 
  verify: (req: any, _res, buf) => { req.rawBody = buf; } 
}));

// Official SDK verification middleware automatically checks x-ghl-signature
// Handles INSTALL (token generation across sub-accounts) and UNINSTALL lifecycle events
app.use('/api/webhooks/ghl', ghl.webhooks.subscribe());

app.post('/api/webhooks/ghl', async (req: any, res) => {
  // Reject spoofed or tampered requests immediately
  if (req.isSignatureValid === false && !req.skippedSignatureVerification) {
    return res.status(401).json({ error: 'Tampered webhook payload: Ed25519 signature invalid' });
  }

  const { type, locationId, data } = req.body;
  
  switch (type) {
    case 'OpportunityStageUpdate':
      await processPipelineProgression(locationId, data);
      break;
    case 'InvoicePaid':
      await provisionCustomerEntitlement(locationId, data);
      break;
  }

  res.status(200).json({ status: 'verified_and_processed' });
});