HubSpot Production Checklist Skill

HubSpot Production Checklist

Overview

Complete checklist for deploying HubSpot CRM integrations to production with health checks, monitoring, and rollback procedures.

Prerequisites

Staging environment tested and verified
Production private app token with minimal scopes
Deployment pipeline configured
Monitoring/alerting ready

Instructions

Step 1: Pre-Deployment Verification

[ ] Production private app created with minimal scopes
[ ] Access token stored in secret manager (not env file)
[ ] .env files in .gitignore
[ ] No hardcoded tokens in source (grep -r "pat-na1" src/)
[ ] Webhook endpoints use HTTPS only
[ ] Webhook signature verification implemented (v3)
[ ] Error handling covers 401, 403, 404, 409, 429, 5xx
[ ] Rate limiting/backoff implemented (numberOfApiCallRetries: 3)
[ ] Batch operations used where possible (max 100/batch)
[ ] All tests passing against developer test account

Step 2: Health Check Endpoint

import * as hubspot from '@hubspot/api-client';

interface HealthCheckResult {
  status: 'healthy' | 'degraded' | 'unhealthy';
  hubspot: {
    connected: boolean;
    latencyMs: number;
    rateLimitRemaining?: number;
  };
  timestamp: string;
}

async function hubspotHealthCheck(): Promise<HealthCheckResult> {
  const client = new hubspot.Client({
    accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  });

  const start = Date.now();
  try {
    // Cheapest possible API call: fetch 1 contact
    await client.crm.contacts.basicApi.getPage(1);
    return {
      status: 'healthy',
      hubspot: {
        connected: true,
        latencyMs: Date.now() - start,
      },
      timestamp: new Date().toISOString(),
    };
  } catch (error: any) {
    const status = error?.code || error?.statusCode || 500;
    return {
      status: status === 429 ? 'degraded' : 'unhealthy',
      hubspot: {
        connected: false,
        latencyMs: Date.now() - start,
      },
      timestamp: new Date().toISOString(),
    };
  }
}

// Express endpoint
app.get('/health', async (req, res) => {
  const result = await hubspotHealthCheck();
  const httpStatus = result.status === 'healthy' ? 200 :
                     result.status === 'degraded' ? 200 : 503;
  res.status(httpStatus).json(result);
});

Step 3: Monitoring Alerts

| Alert | Condition | Severity | |-------|-----------|----------| | HubSpot unreachable | Health check fails 3x | P1 | | High error rate | 5xx errors > 10/min | P1 | | Auth failure | Any 401/403 response | P1 (token revoked?) | | Rate limited | 429 errors > 5/min | P2 | | High latency | p95 > 3000ms | P2 | | Daily quota low | < 10% remaining | P3 |

Step 4: Graceful Degradation

async function withHubSpotFallback<T>(
  operation: () => Promise<T>,
  fallback: T
): Promise<{ data: T; degraded: boolean }> {
  try {
    const data = await operation();
    return { data, degraded: false };
  } catch (error: any) {
    console.error('HubSpot call failed, using fallback:', {
      status: error?.code,
      message: error?.body?.message,
      correlationId: error?.body?.correlationId,
    });
    return { data: fallback, degraded: true };
  }
}

Step 5: Deploy Verification

#!/bin/bash
# post-deploy-verify.sh

echo "=== HubSpot Post-Deploy Verification ==="

# 1. Health check
HEALTH=$(curl -sf https://your-app.com/health | jq -r '.hubspot.connected')
echo "HubSpot connected: $HEALTH"
[ "$HEALTH" = "true" ] || { echo "FAIL: HubSpot not connected"; exit 1; }

# 2. Verify CRM access
STATUS=$(curl -so /dev/null -w "%{http_code}" \
  https://api.hubapi.com/crm/v3/objects/contacts?limit=1 \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN")
echo "CRM API status: $STATUS"
[ "$STATUS" = "200" ] || { echo "FAIL: CRM access denied"; exit 1; }

# 3. Check rate limit headroom
REMAINING=$(curl -sI https://api.hubapi.com/crm/v3/objects/contacts?limit=1 \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  | grep -i 'x-hubspot-ratelimit-daily-remaining' | awk '{print $2}' | tr -d '\r')
echo "Daily rate limit remaining: $REMAINING"

# 4. Check HubSpot status page
HS_STATUS=$(curl -s https://status.hubspot.com/api/v2/summary.json | jq -r '.status.description')
echo "HubSpot platform status: $HS_STATUS"

echo "=== Verification complete ==="

Output

All checklist items verified
Health check endpoint deployed and accessible
Monitoring alerts configured
Graceful degradation implemented
Post-deploy verification script passing

Error Handling

| Issue | Response | |-------|----------| | Health check fails after deploy | Rollback immediately | | 401 in production | Token was regenerated -- update secret and redeploy | | 429 spike after deploy | New code making too many calls -- add batching/caching | | 5xx from HubSpot | Check status.hubspot.com -- enable fallback mode |

Resources

Next Steps

For version upgrades, see hubspot-upgrade-migration.

Agent Skills: HubSpot Production Checklist

Install this agent skill to your local

Skill Files