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
API integration quality
Webhook endpoints
Data handling
Monitoring and alerting
Health check and go-live
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) {
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
Next Steps
For version upgrades, see the intercom-upgrade-migration skill in this pack,
which covers breaking-change migration and dependency bumps.
