Public Integrations

Learn more about public integrations, which are available to all Sentry users.

We've built an example application to help you get started with building on Sentry's integration platform. Check it out for useful code snippets for adding these features in Python and TypeScript. See the docs for more information.

Public integrations are for the "general public" of Sentry users. These start in an unpublished state for development purposes and can be submitted later for approval to publish. For more information, check out the Publication section of this page.

The code examples in the sections below demonstrate a potential use case that involves a Flask app receiving new issue webhooks from Sentry, calling the Sentry API for more data about the issue, and pushing it to Pushover as a generator of desktop/mobile notifications.

Users will have the option to install your integrations on the Integrations page in sentry.io. If your integration is still in an unpublished state, the only Sentry organization that will be able to see or install it will be the organization that created the integration. Once published, clicking the name of the integration will allow users to see a description of your integration and the permissions that will be granted if the user chooses to install.

A list of integrations that a user can install.

After installation, if your user has approved all permissions, Sentry will generate a grant code and an installation ID. This information is sent by way of the installation.created webhook to the webhook URL specified in your configuration.

However, if your integration has a redirect URL configured, the integration redirects the user’s browser to the configured URL with the grant code and installation ID in the query params.

Start building your integration by implementing the redirect URL endpoint, /setup — typically where you exchange the grant code for a token that allows you to make API calls to Sentry:

Copied
import requests
from flask import redirect, request

@app.route('/setup', methods=['GET'])
def setup():
    code = request.args.get('code')
    install_id = request.args.get('installationId')

    url = u'https://sentry.io/api/0/sentry-app-installations/{}/authorizations/'
    url = url.format(install_id)

    payload = {
        'grant_type': 'authorization_code',
        'code': code,
        'client_id': 'your-client-id',
        'client_secret': 'your-client-secret',
    }

    resp = requests.post(url, json=payload)
    data = resp.json()

    token = data['token']
    refresh_token = data['refreshToken']
    # ... Securely store the install_id, token and refresh_token in DB ...

    return redirect('https://sentry.io/settings/')

All public integrations can be installed via a fixed external url: https://sentry.io/sentry-apps/<your-integration-slug>/external-install/, that you can expose to users. Check out this example for Linear: https://sentry.io/sentry-apps/linear/external-install/. Note, if a user has multiple organizations, they'll be asked to choose the one they want for the installation from a dropdown menu.

Public integrations generate authentication tokens after a successful OAuth installation. These tokens automatically expire every eight hours, meaning they must be refreshed manually.

In the initial installation, you'll need the grant code given to you in either the installation webhook request or the redirect URL, in addition to your integration's client ID and client Secret:

Copied
url = u'https://sentry.io/api/0/sentry-app-installations/{}/authorizations/'
url = url.format(install_id)

payload = {
    'grant_type': 'authorization_code',
    'code': code,
    'client_id': 'your-client-id',
    'client_secret': 'your-client-secret',
}

Tokens expire after eight hours, so you'll need to refresh your tokens accordingly:

Copied
def refresh_token(install_id):
    url = u'https://sentry.io/api/0/sentry-app-installations/{}/authorizations/'
    url = url.format(install_id)

    refresh_token = retrieve_refresh_token_from_db(install_id)

    payload = {
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': 'your-client-id',
        'client_secret': 'your-client-secret',
    }

    resp = requests.post(url, json=payload)
    data = resp.json()

    new_token = data['token']
    new_refresh_token = data['refreshToken']
    # ... Securely update the token and refresh_token in DB...

    return new_token

The data you can expect back for both the initial grant code exchange and subsequent token refreshes is as follows:

Copied
{
  "id": "38",
  "token": "ec48bf98637d44c294ead7566513686237e74ab67a074c64b3aaca2d93dbb8f1",
  "refreshToken": "c866f154a65841638d44ee26364409b0a1a67bd642bd46e7a476f34f810712d6",
  "dateCreated": "2019-08-07T20:25:09.870Z",
  "expiresAt": "2019-08-08T04:25:09.870Z",
  "state": null,
  "application": null
}

Typically, if you have the redirect URL configured, there is work happening on your end to "finalize" the installation. If this is the case, we recommend enabling the "Verify Install" option for your integration. Once enabled, you'll need to send a request marking the installation as officially "installed":

Copied
requests.put(
    u'https://sentry.io/api/0/sentry-app-installations/{}/'.format(install_id),
    json={'status': 'installed'},
)

When a user uninstalls your integration, you'll receive an installation.deleted request to your webhook URL. For more information, check out the full Webhooks documentation.

It's possible to use auth tokens from the browser if you allow the origins of the pages making the requests. In the "Authorized JavaScript Origins" field, add each origin (for example, docs.sentry.io) separated by a newline. You don't need to include the protocol (http or https) in the origin. Currently, you can't use any wildcard characters (for example, *.sentry.io), so if you have multiple subdomains, you'll need to add them individually.

Public integrations require a logo image to be uploaded. The requirements for those are:

  • Logo size must be between 256 × 256px and 1024 × 1024px
  • File format must be PNG
  • Background must be transparent (unless the logo takes up the entire space)

If the integration has a UI component, you must also upload an icon that follows these requirements:

  • Icon size must be between 256 × 256px and 1024 × 1024px
  • File must be a PNG in RGBA format
  • All pixels must be black or transparent

When you're ready for the publication process, click "Publish" next to the integration you want to submit. This sends an email to partners@sentry.io, letting us know your integration is ready for review:

Buttons providing the options to publish or delete.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").