Hey ​@mukeshkarkey! Emily here from Support Engineering at Intercom 👋🏼

Here is some information to get you started! 👇🏼

1. Setting Up Intercom Webhooks

• Create a Webhook Subscription:
  In the Intercom Developer Hub, go to your app and navigate to the Webhooks section. Here, you can create a new webhook subscription by specifying:

  • The endpoint URL on your server where notifications should be sent.
  • The event topics (types) you want to subscribe to.

• Permissions:
  Each webhook topic requires specific permissions. When subscribing, ensure your app has the necessary permissions for the topics you select.

• Testing:
  After saving your webhook, Intercom will send a test ping to your endpoint to verify connectivity.

2. Recommended Event Types for Real-Time Updates

For real-time updates related to conversations and messages, consider subscribing to these key webhook topics:

• Conversation Events:

  • conversation.admin.assigned: When a conversation is assigned to an admin.
  • conversation.admin.replied: When an admin replies to a conversation.
  • conversation.user.created: When a user starts a new conversation.
  • conversation.user.replied: When a user replies in a conversation.
  • conversation.closed: When a conversation is closed.
  • conversation.opened: When a conversation is opened.
  • conversation.snoozed: When a conversation is snoozed.

• Message Events:

  • conversation.part.created: When a new part (message) is added to a conversation (covers both user and admin messages).

• Other Useful Events:

  • contact.user.created: When a new user/contact is created.
  • contact.user.updated: When a user/contact is updated.

You can find the full list of available webhook topics in the Intercom developer documentation. Each topic is associated with an Intercom object and a description of the event.

3. Handling and Processing Webhook Payloads

• Payload Structure:
  Each webhook notification is a JSON object with a consistent structure. Key fields include:

  • type: Always "notification_event".
  • topic: The event type (e.g., "conversation.admin.assigned").
  • id: Unique notification ID.
  • app_id: Your Intercom app ID.
  • created_at: Timestamp of the event.
  • data.item: The main object related to the event (e.g., conversation, user, etc.), with its own fields.

  Example payload:

  {
    "type": "notification_event",
    "topic": "conversation.admin.assigned",
    "id": "notif_12345",
    "app_id": "your-app-id",
    "created_at": 1715937890,
    "data": {
      "item": {
        "type": "conversation",
        "id": "67890",
        // ...other conversation fields
      }
    }
  }

   

Hope this helps getting you started with webhooks! You can learn more about webhooks from our docs here 👈🏼