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.

🚧 Multiple permissions

Some topics are associated with multiple permissions. In these cases, you don't need to select all these permissions to subscribe to that topic.

Admin topics

Company topics

Contact topics

Conversation topics

Event topics

Ticket topics

Subscription topics

Visitor topics

Ping

Content stat topics

Webhook notification object

A standard Webhook notification object contains the following fields:

The contents of data.item object will be defined according to its type field. In the example below, 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": "Blue Sun",
      "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.

❗️ Timeout

You have 5 seconds to respond to a notification. If you don't send a response within that time, the notification is treated as failed and will be retried only once after 1 minute.

If you respond with too many error responses, we drop future notifications for a period of 15 minutes.

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" : "Hoban Washburne",
      "unsubscribed_from_emails" : false,
      "custom_attributes" : {}
    }
  }
}

Admin notification object

The Admin notification 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 notification object

We only return the Contact Tag notification 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 notification object is composed from the existing Contact and Tag objects 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.

Content Stat notification object

We only return the Content Stat notification object for Webhooks. You can see an example object below:

{
  "type": "content_stat.series",
  "created_at": "2022-10-11T15:01:07.000Z",
  "content_stat": {
    "id": 1,
    "content_type": "series",
     "content_id": 1,
     "stat_type": "receipt",
     "ruleset_id": 29,
     "content_title": "Untitled",
     "ruleset_version_id": -1,
     "receipt_id": 1,
     "tags": {
       "type": "list",
       "has_more": false,
       "data": [],
       "total_count": 0
     },
     "series_id": 1,
     "series_title": null,
     "node_id": 3
  },
  "contact": {
    "type": "contact",
    "id": "6318db7dfb80c614fe1792b5",
    ...
  }
}

The Content Stat notification object will match our existing Webhook notification object detailed here and contains the following fields:

Content Stat Survey response notification object

The content_stat.survey notification object contains additional payload fields relating to Survey answers. The individual answer key is included in the answer stat type event. The answers key is included in the completion stat type event showing all answers in the Survey.