Set up Webhooks
Webhooks allow you to subscribe to real-time notifications of events happening in Intercom; a Contact created, an incoming Conversation received, or an Outbound Message receipt.
Webhooks Subscriptions are associated with your App and not a single Workspace. You will receive notifications of events from all Workspaces where you install your App.
In this guide, you'll learn how to:
- Configuring your endpoint URL
- Subscribe to a Webhook topic
- Unsubscribe from a Webhook topic
- Manually remove a Webhook Topic subscription
- Remove a related permission scope
For Private Apps, the Intercom data you access is your own, so you're already good to go.
For Public apps, the data you need to access is related to your permission scopes which you'll need to select and be approved for.
Configuring your endpoint URL
To configure your Webhook subscriptions, navigate to your App in your Developer Hub and under the Configure menu, select Webhooks to set up a Webhook subscription.
First, you'll need to set up the endpoint URL to receive notification requests.
Add your full endpoint URL, which must use HTTPS, into the given field.
This URL will receive the HTTP POST notification requests for every topic you have subscribed to. When you add your endpoint URL, it must be able to receive a HEAD request, which we use to validate the URL.
You can find Webhook testing tools online (e.g. ngrok, webhook.site etc) that will allow you to create endpoint URLs for testing and experimentation.
Subscribe to a Webhook topic
You'll then need to select the topics you want to receive the notification requests for.
Click on the Webhook topics dropdown to see all available topics - more information on each topic is available the Webhook models reference page.
Once selected, you should see the topic you've subscribed to appear in the list below. The name, description and permissions it requires to work will also be visible.
🚧 Required permissions showing an error?
You'll need to ensure you've selected the correct permissions on your Authentication page, which the webhook topic requires.
Once you click Save, you will receive notification requests for all of the Topics you've subscribed to from all Workspaces where you install your App, if it's an Internal integration App (i.e. a private App for your use). For Public Apps, users will have to grant permission to access their data during the installation of your App.
Unsubscribe from a Webhook topic
You can stop being sent notifications for topics in two ways:
Manually remove a Webhook Topic subscription
On the Webhooks page of your App, click Edit in the top right of the page and then click Delete on the far right of the topic you want to unsubscribe from.
Remove a related permission scope
On the Authentication page of your App, you can remove the corresponding permission scopes required to subscribe to a Webhook topic. Removing permissions will automatically stop topic notifications from being sent and show the following error on the Webhooks page:
