intercom-webhooks

Receive and verify Intercom webhooks. Use when setting up Intercom webhook handlers, debugging X-Hub-Signature verification, or handling customer messaging events like conversation.user.created, conversation.admin.replied, contact.user.created, or ticket.created.

Jump to install

Repository: hookdeck/webhook-skills
Last source activity: May 11, 2026 at 22:17
Detected SKILL.md language: English
Stars: 79
Forks: 11

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	intercom-webhooks
description	Receive and verify Intercom webhooks. Use when setting up Intercom webhook handlers, debugging X-Hub-Signature verification, or handling customer messaging events like conversation.user.created, conversation.admin.replied, contact.user.created, or ticket.created.
license	MIT
metadata	{"author":"hookdeck","version":"0.1.0","repository":"https://github.com/hookdeck/webhook-skills"}

Intercom Webhooks

When to Use This Skill

Setting up Intercom webhook handlers (Developer Hub topic subscriptions)
Debugging X-Hub-Signature (HMAC-SHA1) verification failures
Handling conversation, contact, and ticket events
Responding to the ping handshake when registering a webhook

Essential Code (USE THIS)

Intercom signs every webhook with HMAC-SHA1 over the raw JSON body using your app's client_secret (from the Developer Hub → Basic Info page). The signature is sent in the X-Hub-Signature header as sha1=<hex_digest> (40 hex chars).

Intercom Signature Verification (JavaScript)

const crypto = require('crypto');

function verifyIntercomWebhook() {
   (!signatureHeader || !clientSecret)  ;

  
   [algorithm, signature] = signatureHeader.();
   (algorithm !==  || !signature)  ;

   expected = crypto
    .(, clientSecret)
    .(rawBody)
    .();

   {
     crypto.(
      .(signature, ),
      .(expected, )
    );
  }  {
     ;
  }
}

const express = require('express');
const app = express();

// CRITICAL: Use express.raw() — Intercom signs the raw body, not parsed JSON
app.post('/webhooks/intercom',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-hub-signature'];

    // Verify signature
    if (!verifyIntercomWebhook(req.body, signature, process.env.INTERCOM_CLIENT_SECRET)) {
      console.error('Intercom signature verification failed');
      return res.status(401).send('Invalid signature');
    }

    // Parse the payload after verification
    const notification = JSON.parse(req.body.toString());
    const topic = notification.topic;

    console.log(`Received ${topic} (notification id: ${notification.id})`);

    // Handle by topic
    switch (topic) {
      case 'ping':
        // Handshake when you save the webhook in the Developer Hub
        console.log('Ping received');
        break;
      case 'conversation.user.created':
        console.log('New conversation from user:', notification.data.item.id);
        break;
      case 'conversation.user.replied':
        console.log('User replied:', notification.data.item.id);
        break;
      case 'conversation.admin.replied':
        console.log('Admin replied:', notification.data.item.id);
        break;
      case 'conversation.admin.assigned':
        console.log('Conversation assigned:', notification.data.item.id);
        break;
      case 'contact.user.created':
        console.log('New user:', notification.data.item.id);
        break;
      case 'contact.lead.created':
        console.log('New lead:', notification.data.item.id);
        break;
      case 'ticket.created':
        console.log('New ticket:', notification.data.item.id);
        break;
      default:
        console.log('Unhandled topic:', topic);
    }

    res.status(200).send('OK');
  }
);

import hmac
import hashlib

def verify_intercom_webhook(raw_body: bytes, signature_header: str, client_secret: str) -> bool:
    if not signature_header or not client_secret:
        return False

    # Intercom sends: sha1=<hex>
    try:
        algorithm, signature = signature_header.split("=", 1)
    except ValueError:
        return False
    if algorithm != "sha1" or not signature:
        return False

    expected = hmac.new(
        client_secret.encode("utf-8"),
        raw_body,
        hashlib.sha1,
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Topic	Description
`ping`	Handshake sent when the webhook is created/saved
`conversation.user.created`	New conversation started by a user
`conversation.user.replied`	User replied to a conversation
`conversation.admin.replied`	Admin (teammate) replied to a conversation
`conversation.admin.assigned`	Conversation assigned to an admin
`conversation.admin.closed`	Admin closed a conversation
`conversation.admin.noted`	Admin added a private note
`contact.user.created`	New user contact created
`contact.lead.created`	New lead contact created
`contact.user.tag.created`	Tag applied to a user contact
`ticket.created`	New ticket created
`ticket.admin.assigned`	Ticket assigned to an admin
`ticket.state.updated`	Ticket state changed

{
  "type": "notification_event",
  "app_id": "abc123",
  "data": {
    "type": "notification_event_data",
    "item": { "type": "conversation", "id": "...", "...": "..." }
  },
  "links": {},
  "id": "notif_<unique_id>",
  "topic": "conversation.user.created",
  "delivery_status": "pending",
  "delivery_attempts": 1,
  "delivered_at": 0,
  "first_sent_at": 1700000000,
  "created_at": 1700000000
}

# Your app's client_secret from Developer Hub → Basic Info
INTERCOM_CLIENT_SECRET=your_app_client_secret

# Forward webhooks to localhost (no account required)
npx hookdeck-cli listen 3000 intercom --path /webhooks/intercom

// Generated with: intercom-webhooks skill
// https://github.com/hookdeck/webhook-skills