--- name: intercom-prod-checklist description: 'Execute Intercom production readiness checklist and rollback procedures. Use when deploying Intercom integrations to production, preparing for launch, or implementing go-live validation. Trigger with phrases like "intercom production", "deploy intercom", "intercom go-live", "intercom launch checklist", "intercom production readiness". ' allowed-tools: Read, Bash(curl:*), Grep version: 1.6.0 license: MIT author: Jeremy Longshore tags: - saas - support - messaging - intercom compatibility: Designed for Claude Code --- # 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](references/implementation.md). - [ ] Pre-flight verification script passes against the production token — full script in [references/examples.md](references/examples.md). - [ ] Rollback procedure rehearsed — see [references/examples.md](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](references/implementation.md)): ```typescript 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](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](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](references/examples.md). - **Rollback procedure** — feature-flag disable, `kubectl rollout undo`, health verification, and webhook teardown: [references/examples.md](references/examples.md). ## Resources - [Intercom Status](https://status.intercom.com) - [Rate Limiting](https://developers.intercom.com/docs/references/rest-api/errors/rate-limiting) - [Webhook Setup](https://developers.intercom.com/docs/webhooks/setting-up-webhooks) - Production health check + monitoring detail: [references/implementation.md](references/implementation.md) - Pre-flight + rollback scripts: [references/examples.md](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. --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/intercom-pack/skills/intercom-prod-checklist/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2025 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/intercom-pack/skills/intercom-prod-checklist/SKILL.md Attribution basis: Source repository record Fields of work: Sales, Customer Support Roles: Customer Success Manager, Support Agent, Technical Support Specialties: API Tools: Intercom Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 49cf7ad0994646f0def2ae7a28b9caeea4cb93180692d9306ded396f26d5aca9