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.
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
ping
Ping
Sent when a post to the Subscription's ping resource is received, or periodically by Intercom. Ping is always subscribed to.
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.
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
A notification object contains the following fields
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.
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
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": {
}
}
}
}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" : {}
}
}
}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 -
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.
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 -
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 |