Integration Platform

Sentry’s integration platform provides a way for external services to interact with Sentry using webhooks, UI components, and the REST API. Integrations using this platform are first-class actors within Sentry.

Example App

If you're new to the integration platform, it might help to get started with an example project. To help you out, we've built an example application, which you can use as a starting point. It demonstrates the different features and data available for your application:

It's a kanban application that uses many of the features available to Sentry integrations and it provides starter code in both Python and TypeScript. It also includes a step-by-step guide to setting up your first integration, as well as documentation and testing advice. Typically, the app should be safely consuming live Sentry data within minutes.

Creating an Integration

In sentry.io, navigate to Settings > Developer Settings. From here, you can choose to create an internal or public integration. Internal integrations can only be used by your organization, whereas public integrations can be published and are available for all Sentry users.

There are several configuration options for your integration, which are described briefly below. Each section provides links to more detailed information.

Webhooks

Webhooks allow your service to get requests about specific resources, depending on your selection. For more information, check out the full Webhooks documentation.

UI Components

The Sentry integration platform provides the ability to add rich UI components to sentry.io itself through a simple, declarative syntax. For more information, check out the full UI Components documentation.

Alerts

You can make any integration available as an action in issue alerts and metric alerts by enabling the "Alert Rule Action" toggle. The integration will then show up as a service in the action section when creating or updating an alert rule:

For your service to receive webhooks for alert rules, users must add to existing rules or create new ones that have Send a notification via <your service> as an action in the rule. Once that's set up, you'll start receiving webhook requests for triggered alerts. For more information about the request and payload, check out the full Webhooks documentation. If you'd like users to provide more app-specific information to handle these webhooks (e.g. assignees, teams, notification channels), consider implementing the alert rule action UI component.

Permissions

Permissions specify what level of access your service requires of Sentry resources. The scopes are directly applied to any API tokens issued to the application. For public integrations, Sentry will prompt users to approve these permissions upon installation. For more information, check out the full documentation on Permissions.

You can't create an integration or change an existing integration to have permissions greater than your own user settings. Permissions are scoped to the organization, so adding scopes for issues and events, projects, or teams will enable access to issues and events, projects, or teams across the organization.

Auth Tokens

Auth tokens are passed using an auth header, and are used to authenticate as a user account with the API. Public integrations require an OAuth flow for tokens. Internal integrations automatically generate tokens after installation. For more information, check out the full Authentication documentation.

Learn More