Intercom prod checklist

Intercom Production Checklist

Overview

Complete checklist for deploying Intercom integrations to production, covering authentication, error handling, rate limits, webhooks, and monitoring. Work the pre-deployment checklist below section by section, run the pre-flight script as the go-live gate, and keep the rollback procedure ready before you launch.

Prerequisites

• A production Intercom workspace with an access token issued from the Developer Hub.
• $INTERCOM_ACCESS_TOKEN exported in the environment where you run the checks.
• curl and jq available for the pre-flight and status probes.
• The integration deployed behind a feature flag so it can be disabled without a redeploy.
• (Optional) $WEBHOOK_URL set if the integration receives Intercom webhooks.

Instructions

Work through the checklist in order. Each group gates a distinct failure class — do not skip a group because "it probably works."

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)

Health check and go-live

• Production health endpoint returns 503 when Intercom is unhealthy — skeleton below, full implementation in references/implementation.md.
• Pre-flight verification script passes against the production token — full script in references/examples.md.
• Rollback procedure rehearsed — see references/examples.md.

Minimal health-check skeleton (the full module classifies degraded-vs-unhealthy from the IntercomError status code and wires an Express /health route — see the full walkthrough):

async function checkIntercomHealth(client: IntercomClient) {
  const start = Date.now();
  try {
    await client.admins.list();
    return { status: "healthy", latencyMs: Date.now() - start };
  } catch (err) {
    // 429 → degraded, 401 → unhealthy + unauthenticated, else unhealthy
    return { status: "unhealthy", latencyMs: Date.now() - start };
  }
}

Output

• A completed checklist where every applicable box is checked before launch.
• A pre-flight run that prints Auth: PASS, current rate-limit headroom, the Intercom status indicator (none = clear), and the webhook endpoint HTTP code. A non-200 auth code exits non-zero and blocks the go-live.
• A /health endpoint returning 200 when Intercom is healthy and 503 when it is degraded or unhealthy, with the classification reason in the JSON body.

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

If the integration is failing in production, run the rollback procedure in references/examples.md: flip the feature flag off first, then roll back the deployment, verify /health, and disable webhooks in the Developer Hub to stop queued deliveries reaching an unhealthy endpoint.

Examples

• Production health check — a full TypeScript module plus Express /health endpoint with status classification: references/implementation.md.
• Pre-flight verification script — a set -euo pipefail bash gate that checks auth, rate-limit headroom, platform status, and webhook reachability, with expected output: references/examples.md.
• Rollback procedure — feature-flag disable, kubectl rollout undo, health verification, and webhook teardown: references/examples.md.

Resources

• Intercom Status
• Rate Limiting
• Webhook Setup
• Production health check + monitoring detail: references/implementation.md
• Pre-flight + rollback scripts: references/examples.md

Next Steps

For version upgrades, see the intercom-upgrade-migration skill in this pack, which covers breaking-change migration and dependency bumps.