Public Integrations

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.

Installation

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.

OAuth Process

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:

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.

Auth Tokens

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

Refreshing Tokens

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:

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:

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:

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

Verifying Installations

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":

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

Uninstallation

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.

Authorized Origins

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.

Image Requirements

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

Publication

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: