intercom-prod-checklist

Intercom Production Checklist

Overview

Complete checklist for deploying Intercom integrations to production, covering authentication, error handling, rate limits, webhooks, and monitoring.

Pre-Deployment Checklist

Authentication and Secrets

• Production access token stored in secret manager (not env files)
• Token has minimal required OAuth scopes
• Token rotation procedure documented and tested
• Separate tokens for dev/staging/production workspaces
• No hardcoded tokens in source code (verified with grep -r "dG9r" .)

API Integration Quality

• All API calls wrapped in error handling (try/catch with IntercomError)
• 429 rate limit retry with exponential backoff implemented
• 5xx server error retry implemented
• Request timeouts configured (recommended: 30s)
• Pagination handles cursor-based iteration correctly
• Contact search uses compound queries efficiently

Webhook Endpoints

• Webhook URL uses HTTPS (Intercom requires it)
• X-Hub-Signature verification implemented (HMAC-SHA1)
• Webhook handler responds within 5 seconds (Intercom timeout)
• Idempotency: duplicate webhooks handled gracefully
• Failed webhook retry handled (Intercom retries once after 1 min)

Data Handling

• PII redacted from logs (emails, names, phone numbers)
• Contact data cached with appropriate TTL
• GDPR deletion handler implemented for contact data
• Custom attributes validated before sending to API

Monitoring and Alerting

• Health check endpoint includes Intercom connectivity test
• Error rate alerting configured (threshold: 5% over 5 min)
• Rate limit usage tracked (alert at 80% of limit)
• Latency monitoring (alert if P95 > 2 seconds)
• Intercom status page monitored (https://status.intercom.com)

Production Health Check

import { IntercomClient, IntercomError } from "intercom-client";

interface IntercomHealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  latencyMs: number;
  authenticated: boolean;
  rateLimitRemaining?: number;
  error?: string;
}

async function checkIntercomHealth(
  client: IntercomClient
): Promise<IntercomHealthStatus> {
  const start = Date.now();
  try {
    const admins = await client.admins.list();
    return {
      status: "healthy",
      latencyMs: Date.now() - start,
      authenticated: true,
      rateLimitRemaining: undefined, // Parsed from response headers
    };
  } catch (err) {
    const latencyMs = Date.now() - start;
    if (err instanceof IntercomError) {
      return {
        status: err.statusCode === 429 ? "degraded" : "unhealthy",
        latencyMs,
        authenticated: err.statusCode !== 401,
        error: `${err.statusCode}: ${err.message}`,
      };
    }
    return {
      status: "unhealthy",
      latencyMs,
      authenticated: false,
      error: (err as Error).message,
    };
  }
}

// Express health endpoint
app.get("/health", async (req, res) => {
  const intercom = await checkIntercomHealth(client);
  const overall = intercom.status === "healthy" ? 200 : 503;
  res.status(overall).json({
    status: intercom.status,
    services: { intercom },
    timestamp: new Date().toISOString(),
  });
});

Pre-Flight Verification Script

#!/bin/bash
set -euo pipefail

echo "=== Intercom Production Pre-Flight ==="

# 1. Auth check
echo -n "Auth: "
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  https://api.intercom.io/me)
[ "$STATUS" = "200" ] && echo "PASS" || { echo "FAIL ($STATUS)"; exit 1; }

# 2. Rate limit headroom
echo -n "Rate limit remaining: "
REMAINING=$(curl -s -D - -o /dev/null \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  https://api.intercom.io/me 2>/dev/null | grep -i x-ratelimit-remaining | awk '{print $2}')
echo "$REMAINING"

# 3. Intercom platform status
echo -n "Intercom status: "
curl -s https://status.intercom.com/api/v2/status.json | jq -r '.status.indicator'

# 4. Webhook endpoint reachable (if configured)
if [ -n "${WEBHOOK_URL:-}" ]; then
  echo -n "Webhook endpoint: "
  WH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$WEBHOOK_URL")
  echo "$WH_STATUS"
fi

echo "=== Pre-flight complete ==="

Rollback Procedure

# 1. Disable Intercom integration via feature flag
curl -X PATCH https://your-config-service/flags/intercom_enabled \
  -d '{"value": false}'

# 2. If using k8s, rollback deployment
kubectl rollout undo deployment/intercom-service
kubectl rollout status deployment/intercom-service

# 3. Verify rollback
curl -s https://your-app.com/health | jq '.services.intercom'

# 4. Disable webhooks in Intercom Developer Hub
# (prevents queued webhook deliveries to unhealthy endpoint)

Error Handling

Alert	Condition	Severity	Action
API unreachable	5xx > 10/min	P1	Enable fallback, check status page
Auth failure	Any 401	P1	Rotate token, verify in Developer Hub
Rate limited	429 > 5/min	P2	Reduce request volume, add queuing
High latency	P95 > 3s	P2	Check Intercom status, enable caching
Webhook failures	Delivery errors	P3	Check endpoint health, verify signature

Resources

• Intercom Status
• Rate Limiting
• Webhook Setup

Next Steps

For version upgrades, see intercom-upgrade-migration.