Setting up Webhooks

You can setup webhooks to be notified of actions with the workspace data where your app is installed.


Webhooks are associated to apps, not workspaces. This means you receive notifications for all workspaces where the app is installed.

Here you’ll learn how to:


Selecting Permissions

For private apps, the 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.

Specify the URL to receive requests

You’ll need to setup your own endpoint to receive notification requests. Take this and insert the full URL (which must be HTTPS) into the given field.

This URL will receive HTTP POST requests for every topic that you set up. When the endpoint is initially added to your configuration, it must also be able to receive a HEAD request which we use to validate the URL.


The quickest way to learn is to experiment and it's best to experiment with something you can't break. While we don't offer this functionality directly from within Intercom, you can find tools online that allow to create webhook URLs and send data to them.

Subscribe to a webhook topic

You’ll then need to select which topics you want to receive the notification request. Click on the dropdown to see all topics - each one will have a description under its name of what you’d be subscribing to:


Once selected, you should see the topic you’ve subscribed to appear below in the given table. Both the name, description, and permissions it requires in order to work will be visible.


Permission showing an error?

You'll need to ensure you've selected the permissions on your Authentication page which the webhook requires.

Once you click Save, you will receive notification requests for the workspaces it’s installed on if it’s a private app (ie. for your own use). For private apps, this will be instant. For public apps, users will have to grant permission to access their data during installation of your app first.

Unsubscribe to a webhook topic

You could stop being sent notifications for topics in two separate ways:

Manually remove subscriptions

On the Webhooks page, click the X on the far right of the subscription in the table:


Remove a related permission scope

On the Authentication page, you can remove corresponding permission scopes that are required to subscribe to a webhook topic. This will automatically stop notification requests from being sent and show the following error on the Webhooks page:


What’s Next

Take a look at the different topics available, their related permissions, and example notifications on the Webhook Models page. For any unanswered questions, go to the FAQ page which covers concepts more in-depth.

Did this page help you?