Intercom security basics

Intercom Security Basics

Overview

Security best practices for Intercom access tokens, webhook signature verification, Identity Verification (HMAC), and least-privilege OAuth scopes.

The full code for each control lives in references/ so this file stays a fast, high-level checklist you can follow end-to-end, then drill into for depth:

• Implementation reference — complete webhook, identity, rotation, and scope code.
• Worked examples — four end-to-end walkthroughs.

Prerequisites

• Intercom access token or OAuth credentials
• Understanding of HMAC cryptographic signatures
• Access to Intercom Developer Hub

Instructions

Step 1: Secure Token Storage

Store every secret in .env (or a secret manager) and never commit it.

# .env (NEVER commit to git)
INTERCOM_ACCESS_TOKEN=dG9rOmFiY2RlZmdoaQ==
INTERCOM_WEBHOOK_SECRET=your-webhook-signing-secret
INTERCOM_IDENTITY_SECRET=your-identity-verification-secret

# .gitignore (mandatory entries)
.env
.env.local
.env.*.local

Then scan history for anything already leaked — use Grep (or the shell) to search committed content for token markers:

git log --all -p | grep -i "INTERCOM_ACCESS_TOKEN\|dG9r" | head -5
# If found: rotate the token immediately, then use git-filter-repo to remove it.

Step 2: Webhook Signature Verification (X-Hub-Signature)

Intercom signs webhook notifications with HMAC-SHA1 using X-Hub-Signature. Verify it on every incoming webhook against the raw request body, using a timing-safe comparison, and reject mismatches with 401:

const expectedSignature = "sha1=" + crypto
  .createHmac("sha1", secret)
  .update(payload)   // payload = raw Buffer, not parsed JSON
  .digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));

Full Express handler: implementation.md — Webhook Signature Verification.

Step 3: Identity Verification (User Hash)

Identity Verification blocks impersonation by requiring an HMAC-SHA256 of the user's identifier, generated server-side only:

crypto.createHmac("sha256", process.env.INTERCOM_IDENTITY_SECRET!)
  .update(userId)
  .digest("hex");

Return this user_hash alongside app_id and user_id for Messenger boot. Full code: implementation.md — Identity Verification.

Step 4: Least-Privilege OAuth Scopes

Only request the scopes your app actually uses — excess scopes widen the blast radius of a leaked token. The full use-case → scope mapping is in implementation.md — Least-Privilege OAuth Scopes. For example, a read-only contacts integration needs just Read contacts, not full CRM read/write.

Step 5: Token Rotation Procedure

Rotate by adding the new token to your secret manager and deploying before revoking the old one, so no window exists without a live token. Full procedure (AWS / GCP / Vault examples + verification curl): implementation.md — Token Rotation Procedure.

Output

Applying this skill produces:

• A .env (or secret-manager entry) holding INTERCOM_ACCESS_TOKEN, INTERCOM_WEBHOOK_SECRET, and INTERCOM_IDENTITY_SECRET, with .env patterns added to .gitignore.
• A webhook route that returns 200 for valid X-Hub-Signature deliveries and 401 for missing or forged signatures.
• Server-side user_hash generation wired into the Messenger boot settings.
• An OAuth app requesting only least-privilege scopes.
• A documented, tested token-rotation runbook.

The end state is the completed Security Checklist below, every box ticked.

Security Checklist

• Access tokens stored in environment variables or secret manager
• .env files in .gitignore
• Different tokens for dev/staging/production workspaces
• Webhook signatures verified on every request (X-Hub-Signature)
• Identity Verification enabled (user_hash)
• OAuth scopes are minimal (least privilege)
• Token rotation procedure documented and tested
• Git history scanned for leaked credentials
• HTTPS enforced for all webhook endpoints

Error Handling

Security Issue	Detection	Mitigation
Leaked token in git	git log -p | grep dG9r	Rotate immediately, remove from history
Invalid webhook signature	401 from verification	Check secret matches Developer Hub
Missing Identity Verification	Intercom dashboard warning	Implement user_hash on server
Excessive OAuth scopes	Scope audit	Remove unnecessary scopes
Token never rotated	Age tracking	Schedule quarterly rotation

Examples

Four end-to-end walkthroughs live in references/examples.md:

1. Secure a fresh integration from zero — store the three secrets in .env and prove none are staged.
2. Scan an existing repo for a leaked token — git log --all -p | grep for token markers before shipping.
3. Add webhook verification to an Express app — reject forged payloads with 401 via X-Hub-Signature.
4. Turn on Identity Verification for the Messenger — server-side user_hash to stop impersonation.

Quick sanity check that a rotated token is live:

curl -s https://api.intercom.io/me \
  -H "Authorization: Bearer $NEW_TOKEN" | jq '.type'
# Should return "admin"

Resources

• Authentication
• OAuth Scopes
• Webhook Notifications
• Identity Verification

Next Steps

For production deployment hardening beyond these basics, see the intercom-prod-checklist skill, which covers rate limiting, error monitoring, and staged rollout for the same integration.