Skip to main content
AI/MLjeremylongshore

intercom-deploy-integration

'Deploy Intercom integrations to Vercel, Fly.io, and Cloud Run with proper

Stars
2,267
Source
jeremylongshore/claude-code-plugins-plus-skills
Updated
2026-05-31
Slug
jeremylongshore--claude-code-plugins-plus-skills--intercom-deploy-integration
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/jeremylongshore/claude-code-plugins-plus-skills/HEAD/plugins/saas-packs/intercom-pack/skills/intercom-deploy-integration/SKILL.md -o .claude/skills/intercom-deploy-integration.md

Drops the SKILL.md into .claude/skills/intercom-deploy-integration.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Intercom Deploy Integration

Overview

Deploy Intercom-powered applications to Vercel, Fly.io, or Google Cloud Run with proper secret management, signed webhook endpoints, and health checks. The workflow is the same across platforms — provision two secrets, deploy, wire a /health probe, then register the webhook URL — and each platform's copy-ready code lives in references/implementation.md.

Prerequisites

  • Intercom production access token
  • Platform CLI installed (vercel, flyctl, or gcloud)
  • Application with Intercom integration ready for deployment

Authentication

Two secrets drive every deployment. INTERCOM_ACCESS_TOKEN authenticates API calls (passed to the SDK as new IntercomClient({ token })); INTERCOM_WEBHOOK_SECRET is the Developer Hub signing secret used to verify inbound webhook payloads (HMAC-SHA1 over the raw body, compared against the X-Hub-Signature header). Store both in the platform's secret store — never hardcode them: vercel env add, fly secrets set, or Cloud Run Secret Manager. A mismatched webhook secret returns 401 Invalid signature; an invalid token surfaces as a degraded health check rather than a hard failure.

Instructions

Pick the platform that matches your stack. Each step below shows the essential skeleton; open references/implementation.md for the complete webhook handler, vercel.json, fly.toml, Cloud Run deploy script, and shared health-check code.

Step 1: Choose a platform and provision secrets

  • Vercel (serverless): vercel env add INTERCOM_ACCESS_TOKEN production then vercel env add INTERCOM_WEBHOOK_SECRET production.
  • Fly.io (long-running): fly secrets set INTERCOM_ACCESS_TOKEN=... INTERCOM_WEBHOOK_SECRET=....
  • Cloud Run (container): store both in Secret Manager and mount with --set-secrets.

Step 2: Write the signed webhook handler

Read the raw request body (disable body parsing), recompute the HMAC-SHA1 signature, and compare with crypto.timingSafeEqual. Return within 5 seconds — queue slower work:

const expected = "sha1=" + crypto
  .createHmac("sha1", process.env.INTERCOM_WEBHOOK_SECRET!)
  .update(rawBody)
  .digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return res.status(401).end();

Write this to api/webhooks/intercom.ts (Vercel) or the equivalent route. Full handler, including the raw-body read and the Vercel config export, is in the Vercel section of references/implementation.md.

Step 3: Add a Intercom-aware health check

Expose a /health route that calls client.admins.list() and reports healthy / degraded with latency. Edit your platform config to wire it as the liveness probe (fly.toml checks block, or Cloud Run's default). Full code is in the Health Check section of references/implementation.md.

Step 4: Deploy

Run the platform deploy command: vercel --prod, fly deploy, or the gcloud run deploy script. Verify with curl https://your-domain.com/health.

Step 5: Register the webhook URL

In Developer Hub > Webhooks, set the endpoint to https://your-domain.com/api/webhooks/intercom, select topics (see the reference table below), copy the signing secret into your platform secrets, and send a test notification to confirm a 200.

Webhook Topics Reference

Topic Fires When
conversation.user.created New conversation from contact
conversation.user.replied Contact replies
conversation.admin.replied Admin replies
conversation.admin.closed Conversation closed
contact.created New contact created
contact.signed_up Lead converts to user
contact.tag.created Tag applied to contact
user.created New user (legacy topic)

Output

A successful run produces a deployed service reachable over HTTPS with:

  • Both INTERCOM_ACCESS_TOKEN and INTERCOM_WEBHOOK_SECRET stored in the platform's secret store (never in source).
  • A signature-verifying webhook endpoint returning 200 { "received": true } for valid payloads and 401 for bad signatures.
  • A /health endpoint returning {"status":"healthy","services":{"intercom":{"connected":true,"latencyMs":142}}}.
  • The webhook registered in Developer Hub with a passing test notification.

Error Handling

Issue Cause Solution
Webhook 401 Signature mismatch Verify secret matches Developer Hub
Cold start timeout Serverless spin-up Set min instances > 0
Secret not found Missing config Verify secrets with platform CLI
Health check failing Token invalid in prod Verify production token
Webhook delivery fails 5s timeout exceeded Queue events, process async

Examples

Start from the Vercel skeleton, then drill into the platform you're shipping to:

vercel env add INTERCOM_ACCESS_TOKEN production
vercel env add INTERCOM_WEBHOOK_SECRET production
vercel --prod

Full end-to-end walkthroughs for Vercel, Fly.io, and Cloud Run — including expected output and how to read a failing test notification — are in references/examples.md.

Resources

Next Steps

For webhook payload handling and event-processing patterns after deployment, see the intercom-webhooks-events skill in this pack.