Webhook Models

Webhook topics

The following topics are available and you can be notified when an action relating to that topic occurs. You just need to tell us where to send the notification. The 'Item Type' column shows the API type that will be sent as the data of the Notification.

Topic
Item Type
Description

conversation.user.created

Conversation

Subscribe to user and lead initiated messages

conversation.user.replied

Conversation

Subscribe to user conversation replies

conversation.admin.replied

Conversation

Subscribe to admin conversation replies

conversation.admin.single.created

Conversation

Subscribe to admin initiated 1:1 conversation

conversation.admin.assigned

Conversation

Subscribe to admin conversation assignments

conversation.admin.noted

Conversation

Subscribe to admin conversation notes

conversation.admin.closed

Conversation

Subscribe to admin conversation closes

conversation.admin.opened

Conversation

Subscribe to admin conversation opens

conversation.admin.snoozed

Conversation

Subscribe to admin conversation snoozes

conversation.admin.unsnoozed

Conversation

Subscribe to admin conversation unsnoozes

conversation_part.tag.created

Conversation

Subscribe to conversation parts being tagged

user.created

User

Subscribe to user creations

user.deleted

User

Subscribe to user deletions.

user.unsubscribed

User

Subscribe to user unsubscriptions from email

user.email.updated

User

Subscribe to user's email address being updated

user.tag.created

UserTag

Subscribe to users being tagged.

user.tag.deleted

UserTag

Subscribe to users being untagged

contact.created

Lead

Subscribe to Lead creations

contact.signed_up

Lead

Subscribe to Leads converting to a User

contact.added_email

Lead

Subscribe to Leads adding email

contact.tag.created

ContactTag

Subscribe to leads being tagged.

contact.tag.deleted

ContactTag

Subscribe to leads being untagged.

visitor.signed_up

Visitor

Subscribe to visitors converting to a User

company.created

Company

Subscribe to company creations

event.created

Event

Subscribe to events (Beta!)

ping

Ping

Sent when a post to the Subscription's ping resource is received, or periodically by Intercom. Ping is always subscribed to.

Webhook and permissions

Each webhook topic is associated with one or more permission scopes. If you would like to setup a webhook for a particular topic then you will need to select the appropriate permission scope to be able to request a notification for that topic.

Multiple permissions

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

Webhook topic
Works with permissions
Groups

conversation_part.tag.created

Read conversations

Conversation data

conversation.admin.assigned

Read conversations

Conversation data

conversation.admin.closed

Read conversations

Conversation data

conversation.admin.noted

Read conversations

Conversation data

conversation.admin.opened

Read conversations

Conversation data

conversation.admin.replied

Read conversations

Conversation data

conversation.admin.single.
created

Read conversations

Conversation data

conversation.user.created

Read conversations

Conversation data

conversation.user.replied

Read conversations

Conversation data

contact.added_email

Read users and companies, Read and write users,
Read one user and one company

Customer data

contact.created

Read users and companies, Read and write users,
Read one user and one company

Customer data

contact.signed_up

Read users and companies, Read and write users,
Read one user and one company

Customer data

contact.tag.created

contact.tag.deleted

user.created

Read users and companies, Read and write users,
Read one user and one company

Customer data

user.deleted

Read users and companies, Read and write users,
Read one user and one company

Customer data

user.email.updated

Read users and companies, Read and write users,
Read one user and one company

Customer data

user.tag.created

Read users and companies, Read and write users,
Read one user and one company

Customer data

user.tag.deleted

Read users and companies, Read and write users,
Read one user and one company

Customer data

user.unsubscribed

Read users and companies, Read and write users,
Read one user and one company

Customer data

visitor.signed_up

Read users and companies, Read and write users,
Read one user and one company

Customer data

event.created

Read events

Customer event data

company.created

Read users and companies, Read one user and one company

Company data

Webhook Notification object

A notification object contains the following fields

Attribute
Type
Description

type

string

_value is 'notification_event'_

id

string

The Intercom defined id representing the notification.

self

string

The Intercom defined URL for the subscription. Optional

created_at

timestamp

The timestamp the notification was created.

topic

string

Corresponds to a topic, eg 'company.created', 'conversation.assigned'

delivery_attempts

number

The number of times this notification has been attempted.

first_sent_at

timestamp

The first time the delivery was attempted.

data

object

A container for the data associated with the notification.

data.item

object

The data associated with the notification, which will have a 'type' field.

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.

Handling webhook notifications

When you setup a subscription you will receive notifications on your chosen topics. How you handle those notifications, i.e. the HTTP status code returned, will determine the subsequent state of that subscription. Please see below for a list of how a subscription will respond to these status codes

Response Code
Description
Subscription Action

2xx

Success - Indicates subscription was delievered

Timeout is 5 seconds. If you don't send a response inside that time notification is treated as failed and will be retried only once after 1 minute

429

Too many requests

When a 429 is received all notification from that subscription will be throttled. Depending on rate of delivery this delay can be between 1 minute to 2 hours. If 429s continue and any notification is delayed for > 2 hours we will drop that notification.

4xx*, 5xx

Client or service errors

Retry after 1 minute. If 2nd retry fails we mark notification delivery as failed.

*Excluding 429

Example Notification Object

{
  "type": "notification_event",
  "topic": "company.created",
  "id": "notif_ccd8a4d0-f965-11e3-a367-c779cae3e1b3",
  "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": {
      }
    }
  }
}

Signed Notifications

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

The value of this X-Hub-Signature header is computed 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 a SHA-1 signature computed using the HMAC algorithm as defined in RFC2104.

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

Example Signed Request

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" : {}
    }
  }
}

Contact tag model for webhooks

The Contact Tag model is only returned for webhooks. It is not used with the Lead (i.e. contact) or Tag endpoints themselves. You can see an example object below

Example Contact Tag Object

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

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

Attribute
Type
Description

type

string

_value is 'contact_tag'_

created_at

timestamp

The time the contact tag object was created

tag

Tag

The tag that was added or removed.

contact

contact

The contact that was tagged or untagged.

User tag model for webhooks

The User Tag model is only returned for webhooks. It is not used with the User or Tag endpoints themselves. You can see an example object below

Example User Tag Object

{
  "type": "user_tag",
  "created_at": 1392731331,
  "tag" : {
      "id": "17513",
      "name": "independent",
      "type": "tag"
    },
  "user" : {
      "type": "user",
      "id": "530370b477ad7120001d",
      "user_id": "25"
  }
}

A user tag is composed from the existing user and tag JSON and is sent when users are tagged and untagged via the user.tag.created and user.tag.deleted topics -

Attribute
Type
Description

type

string

_value is 'user_tag'_

created_at

timestamp

The time the user tag object was created

tag

Tag

The tag that was added or removed.

user

User

The user that was tagged or untagged.


What's Next

Make sure you understand how to setup, update, and remove webhooks with the Setting up Webhooks guide. For any unanswered questions, take a look at the FAQ page which covers concepts more in-depth.

Setting up Webhooks
Webhooks FAQ