| name | intercom-webhooks-events |
| description | Implement Intercom webhook handling and data event tracking.
Use when setting up webhook endpoints, processing Intercom notifications,
or submitting custom data events for contact activity tracking.
Trigger with phrases like "intercom webhook", "intercom events",
"intercom webhook signature", "handle intercom events", "intercom data events",
"track intercom events".
|
| allowed-tools | Read, Write, Edit, Bash(curl:*) |
| version | 1.6.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","support","messaging","intercom"] |
| compatibility | Designed for Claude Code |
Intercom Webhooks & Events
Overview
Handle incoming Intercom webhooks (notifications) with signature verification and implement outbound data event tracking via the Events API. Incoming webhooks push conversation and contact changes to your endpoint; outbound data events push custom activity into Intercom for segmentation and messaging.
The full, copy-ready code lives in references/; this file walks the workflow at a high level so you can follow it start to finish, then drill in for depth.
Prerequisites
- HTTPS endpoint accessible from internet
- Webhook secret from Intercom Developer Hub
- Access token from Intercom Developer Hub (for outbound data events)
intercom-client SDK installed- Redis or database for idempotency (recommended)
Authentication
Two distinct credentials, both issued from the Intercom Developer Hub and read from environment variables — never hard-code them:
- Incoming webhooks are verified with
INTERCOM_WEBHOOK_SECRET. Intercom signs every delivery with HMAC-SHA1 in the X-Hub-Signature header; you recompute the digest over the raw request body and compare with crypto.timingSafeEqual. Reject any request that fails or is missing the header.
- Outbound data events authenticate with a bearer
INTERCOM_ACCESS_TOKEN passed to IntercomClient.
Instructions
Read the relevant reference file, then use Write/Edit to scaffold the handler into the target project.
- Build the signed endpoint. Create an Express route that captures the raw body (
express.raw), verifies the X-Hub-Signature HMAC-SHA1 digest against INTERCOM_WEBHOOK_SECRET, and returns 200 within 5 seconds — Intercom treats a slower response as a failure. Respond first, process after. See incoming webhooks walkthrough Step 1.
- Model the payload. Every delivery is a
notification_event envelope carrying topic, id, and data.item (the changed resource). Type it so the router is safe. See incoming webhooks walkthrough Step 2.
- Route by topic. Dispatch on
notification.topic through a handler map; log and no-op unknown topics rather than throwing. Pick topics from the . See Step 3.
