Webhooks are notifications that you can subscribe to which allow you to receive API updates when things happen in your app such as conversation replies, or when new users are created.
Webhooks solve some common API integration problems. With webhooks you will:
- Avoid polling the API to receive up-to-date information.
- Have notifications delivered to services other than ones you are calling Intercom's API with.
- Receive notifications that are not a result of other API calls
To use webhooks you can create a subscription via the API or the webhooks tool at developers.intercom.com. Each subscription has a URL which will receive notifications, and a set of topics you want to be notified about. Once the subscription is created the URL will be sent notifications about those topics.
How to create a Webhook
Each subscription is associated with an app, and an app may have multiple subscriptions. An App's subscriptions are visible in the webhooks section of your dashboard in the Developer Hub or via the API.
A webhook subscription can be configured in the "Webhooks" section of your dashboard in the Developer Home - you can get to this by visiting developers.intercom.com or via the ‘Developer tools’ link in your app settings. Clicking "Create webhook" will show a form for creating the subscription.
Using the API. You can send a webhook subscription JSON object to the API. The subscription will contain the URL and topics for the webhook, and may also contain a secret used to sign each notification (see "Securing Webhooks" below).
"topics": ["company", "conversation.user.created"],
The following topics and sub-topics can be subscribed to
- All: subscribe to all notifications.
- Conversations: subscribe to all conversation notifications. You can also subscribe to the following sub-topics - user initiated messages, user replies, admin replies, admin notes, admin assigns, conversation opens and closers.
- Users: subscribe to all user notifications. You can also subscribe to the following sub-topics - new user creations, users unsubscribing from email, tagging of users.
- Companies: subscribe to new company creations.
See this topics section in our API documentation for more details.
We support HTTP and HTTPS subscription URLs, and we recommend you provide a HTTPS URL to protect notifications.
If you are creating subscriptions via the API you can also supply a "hub secret" value. This tells the API to sign the request before delivering it. The value of the hub_secret is used as the key to create a signature of the notification data, and is sent along with the notification, which can then be verified by the receiving server. See the signed notification API documentation for details.
When you create a new webhook subscription, we'll send a ping notification to the supplied URL. You can trigger a ping again by calling the ping resource for a subscription. Your webhook receiver should be able to handle a ping submission as the API may send them at any time.
Webhook Delivery Feeds
Each subscription has a sent and error feed in the API. The sent feed is simply a list of all the recent notifications that have been delivered to your webhook. The error feed for a subscription contains a list delivery failures. Each entry in the error feed contains the failed notification along with the details of the HTTP request and response, which is useful for debugging what happened.
The feeds are not intended to be permanent archives and notifications may only retrievable for a period of time; a best effort is made to keep 30 days of notification data.