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. INTERCOMACCESSTOKEN authenticates API calls

(passed to the SDK as new IntercomClient({ token })); INTERCOMWEBHOOKSECRET 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 INTERCOMACCESSTOKEN production then

vercel env add INTERCOMWEBHOOKSECRET production.

• Fly.io (long-running): fly secrets set INTERCOMACCESSTOKEN=... INTERCOMWEBHOOKSECRET=....
• 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

Output

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

• Both INTERCOMACCESSTOKEN and INTERCOMWEBHOOKSECRET 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

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

• Full implementation code
• Worked deploy examples
• Webhook Setup
• Webhook Topics
• Vercel Docs
• Fly.io Docs
• Cloud Run Docs

Next Steps

For webhook payload handling and event-processing patterns after deployment, see the

intercom-webhooks-events skill in this pack.