Integrating Intercom
Auth: OAuth 2.0 · Partner program: required · Setup time: about 25 minutes · Last verified: 2026-05-23
Intercom is a messaging-first customer-support and engagement platform. The adapter wraps the Intercom REST API and exposes conversations, contacts, companies, admins, and tags into the canonical customer-support schema.
Auth model
Section titled “Auth model”- OAuth 2.0 Authorization Code grant. Authorize at
https://app.intercom.com/oauth. Exchange via POST tohttps://api.intercom.io/auth/eagle/token. - Access tokens are long-lived bearer tokens; Intercom does not currently rotate them on a fixed schedule. Use the
/meendpoint to validate and re-prompt the user if it 401s.
Prerequisites
Section titled “Prerequisites”- An Intercom workspace at intercom.com.
- A registered app in the Developer Hub (
developers.intercom.com). On the Authentication page, tick Use OAuth and supply at least one HTTPS redirect URL. - To distribute the app to other Intercom customers, the app must be submitted for review and listed on the Intercom App Store. Internal apps used only by your own workspace can skip review.
Configure in admin
Section titled “Configure in admin”- Open
/platformsin the admin UI, filter to Customer Support, click Intercom. - Fill Configure:
clientId— from your Intercom app’s Basic Information page.clientSecret— from your Intercom app’s Basic Information page.redirectUri—${PUBLIC_BASE_URL}/auth/customer-support/intercom/callback.
- Enable the adapter.
Required scopes
Section titled “Required scopes”Intercom scopes are declared on the Authentication page and granted at install. Common selections for the canonical schema:
Read and list users and companies,Write users and companiesRead conversations,Write conversationsRead adminsRead tags,Write tagsRead tickets,Write ticketsRead events,Write events
Over-scoping is the most common reason apps are rejected in the marketplace review — request only what the integration needs.
Webhooks
Section titled “Webhooks”Configure webhooks under your app’s Webhooks page. Intercom signs each delivery with HMAC-SHA1 using your app’s Client Secret as the key; the signature arrives in the X-Hub-Signature header as sha1=<hex>.
Verify against the raw request body byte-for-byte — re-serialising JSON changes the digest. Subscribe to conversation.*, contact.*, company.*, and ticket.* topics.
Quirks worth knowing
Section titled “Quirks worth knowing”- Marketplace review for production distribution. Internal apps run without review; public distribution requires Intercom App Store approval. Plan for revisions if you ask for write scopes beyond your stated use case.
X-Hub-Signatureis SHA-1. Many platforms use SHA-256 — Intercom does not.- Regional hosts exist (
api.eu.intercom.io,api.au.intercom.io). Readapp.regionfrom the token response; the adapter routes requests accordingly. - JWT signing of body affects verification. When porting verification code, use the exact raw body — Python’s
json.dumps(...)re-serialisation breaks signature comparison.
References
Section titled “References”opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.