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.

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.

The quickest way to learn is to experiment and it's best to experiment with something you can't break. The simplest tool for testing webhooks is Request Bin. Request Bin lets you create a webhooks URL and send data to it to see how it's recognized in a human readable form. Go to requestbin.com, click Create a RequestBin, then copy the URL it gives you and paste it as your endpoint URL for testing.

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.

Webhook Models
Webhooks FAQ

Setting up Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.