Integration Platform
Learn how to create integrations so that external services can interact with Sentry.
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.
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.
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 allow your service to get requests about specific resources, depending on your selection. For more information, check out the full Webhooks documentation.
In order to receive webhook events, you must specify the webhook URL when creating an integration. After you've specified the webhook URL, you'll be able to toggle on "Alert Rule Action" and create issue and metric alerts that send notifications to your integration.
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.
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. The gif below shows how to set up an integration that can receive Sentry alerts.
For your service to receive webhooks for alert rules, you must have Send a notification via <your integration> 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 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 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.
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").