Webhook Topics

You can subscribe to the following Webhook topics, and you will receive notifications on your endpoint URL when an event occurs. The 'Object' column shows the Intercom object related to the event sent as part of the notification.

Each Webhook topic is associated with one or more permissions. When you set up a subscription to a particular topic, you will need to select the appropriate permissions to be able to receive a notification for that topic.

Admin topics

Company topics

Contact topics

Conversation topics

Event topics

Subscription topics

Visitor topics

Ping

Webhook notification object

A notification object contains the following fields:

The contents of data.item object will be defined according to its type field. In the example to the right, the type value of Company indicates a company object.

{
  "type": "notification_event",
  "topic": "company.created",
  "id": "notif_ccd8a4d0-f965-11e3-a367-c779cae3e1b3",
  "app_id" : "a86dr8yl",
  "created_at": 1392731331,
  "delivery_attempts": 1,
  "first_sent_at": 1392731392,
  "data": {
    "item": {
      "type": "company",
      "id": "531ee472cce572a6ec000006",
      "name": "Example Company Inc.",
      "company_id": "6",
      "remote_created_at": 1394531169,
      "created_at": 1394533506,
      "updated_at": 1396874658,
      "custom_attributes": {
      }
    }
  }
}

Handling Webhook notifications

You will receive notifications on your chosen topics when you set up a subscription. How you handle those notifications, i.e. the HTTP status code returned, will determine the subsequent state of that subscription.

Signed notifications

Intercom signs webhook notifications via an X-Hub-Signature header. We do this so that you can verify that the notification came from Intercom by decoding the signature.

We compute the value of this X-Hub-Signature header by creating a signature using the body of the JSON request and your App's client_secret value, which you can find on the Basic Info page of your App.

The signature is the hexadecimal (40-byte) representation of an SHA-1 signature computed using the HMAC algorithm defined in RFC2104.

The X-Hub-Signature header value starts with the string sha1= followed by the signature.

POST https://example.org/hooks
User-Agent: intercom-parrot-service-client/1.0
X-Hub-Signature: sha1=21ff2e149e0fdcac6f947740f6177f6434bda921
Accept: application/json
Content-Type: application/json

{
  "type" : "notification_event",
  "id" : "notif_78c122d0-23ba-11e4-9464-79b01267cc2e",
  "topic" : "user.created",
  "app_id" : "a86dr8yl",
  "data" : {
    "type" : "notification_event_data",
    "item" : {
      "type" : "user",
      "id" : "530370b477ad7120001d",
      "user_id" : "25",
      "name" : "Joe Example",
      "unsubscribed_from_emails" : false,
      "custom_attributes" : {}
    }
  }
}

Admin object for Webhooks

The Admin object is similar to the model returned via the API. You can see an example object below:

{
	"type": "admin",
	"id": "1",
	"name": "John Doe",
	"email": "john.doe@intercom.io",
	"job_title": "CEO",
	"away_mode_enabled": true,
	"away_mode_reassign": false,
	"away_status_reason": "🍔 On lunch",
	"has_inbox_seat": true,
	"team_ids": []
}

Contact Tag object for Webhooks

We only return the Contact Tag object for Webhooks. You can see an example object below:

{
  "type": "contact_tag",
  "created_at": 1392731331,
  "tag" : {
      "id": "1287",
      "name": "independent",
      "type": "tag"
    },
  "contact" : {
      "type": "contact",
      "id": "1287ab1287fefe",
        ........
  }
}

A contact tag is composed from the existing contact and tag JSON and is sent when contacts are tagged and untagged via the contact.user.tag.created, contact.lead.tag.created, contact.lead.tag.deleted and contact.user.tag.deleted topics.