intercom-security-basics

name	intercom-security-basics
description	Apply Intercom security best practices for tokens, webhook verification, and scopes. Use when securing access tokens, implementing webhook signature validation, or configuring least-privilege OAuth scopes. Trigger with phrases like "intercom security", "intercom secrets", "secure intercom", "intercom webhook signature", "intercom token rotation".
allowed-tools	Read, Write, Grep
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","support","messaging","intercom"]
compatibility	Designed for Claude Code

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
  .();
 crypto.(.(signature), .(expectedSignature));