So you want to integrate with the Sentry Integration Platform. Great! We're looking forward to it 🎉 That's why we built out this codebase; clone and fork away!
This repository contains some starter code for interfacing with the Integration Platform that is meant to be a tool for your reference. It demos an example kanban application which will be integrating with Sentry to auto-generate tickets, links and create a richer user experience.
In it, we'll be covering the following features:
- Handling Installation (with OAuth)
- Using the Sentry API
- Verifying Installations
- Handling Uninstallations
- Handling Webhooks
- Issues
- Comments
- Alerts
- Implementing UI Components
- Issue Linking
- Alert Rule Actions
If we missed something, or you're still having trouble, feel free to create an issue, and we'll see what we can do! Happy Developing!
- Sentry - You must be either a Manager or Owner of an organization on Sentry.
- Docker - This demo application uses Docker to setup and communicate between its different services.
- Disable your adblocker - This is a common pitfall that developers fall into when building on Sentry, doing it early can save your time down the line!
- Select a codebase - This demo application comes with a mock frontend and a choice between two backends, one in Node (Express, Sequelize, TypeScript) and another in Python (Flask, SQLAlchemy). Pick the commands and environment that is more appropriate for your implementation.
- A local PostgreSQL DB Client (Optional) - Great for viewing changes on objects, and debugging, removing, or editing data. We suggest Postico.
Before setting anything up, you must determine the type of integration you're building on Sentry's Integration Platform.
Public integrations are meant to be accessed by all Sentry Customers, regardless of whether or not they belong to your organization.
If you only wish to provide an application to your team or organization, you should probably develop an Internal integration. These are far easier to get up and running, as they skip the OAuth installation process and become immediately available for webhooks, UI components or API usage.
This tutorial assumes you're building a public integration, but most of the steps are identical for internal integrations unless stated otherwise.
To get started, you'll need access to ngrok. ngrok is a tool which lets you expose your locally running servers to the internet. Since Sentry requires an HTTP connection to your application, this is the easiest way to test changes without having to deploy constantly. You can find installation instructions here.
Make sure you add an authtoken in order to generate a configuration file.
Copy the included ngrok-config.example.yml as ngrok-config.yml, with your ngrok auth token in the authtoken field. Optionally, you can also assign static hostnames to your different tunnels if you've reserved them via ngrok's domains settings page on paid plans.
This will let you easily set up your tunnels with:
ngrok start --all --config ngrok-config.ymlWith ngrok running, you'll be presented with an interface that might look like the following:
ngrok
Session Status online
Account Sentry (Plan: Pro)
Version 3.0.3
Region United States (us)
Latency 96.595653ms
Web Interface http://127.0.0.1:4040
Forwarding https://frontend-hostname.ngrok.io -> http://localhost:3000
Forwarding https://backend-py-hostname.ngrok.io -> http://localhost:5100
Forwarding https://backend-ts-hostname.ngrok.io -> http://localhost:5200
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
Take a note of the forwarding addresses (ending with .ngrok.io), as you'll need them to setup your integration within Sentry. These addresses will be randomly generated UUIDs by default if you did not specify custom hostnames in your configuration. You can identify which address coordinates with which server by the port they map to on your local machine. By default:
[Frontend address] -> http://localhost:3000
[Python backend address] -> http://localhost:5100
[Typescript backend address] -> http://localhost:5200
Though, if you change your environment variables in Step 3, from their default values, this will not be the case.
Next, we'll be setting up an integration for our app to connect to, and a project to which we'll send test errors. To set up the integration, perform the following steps in your Sentry instance.
- Click Settings > Developer Settings > Create New Integration > Public Integration
- Give your integration an appropriate name and author.
- Specify a Webhook and Redirect URL with your ngrok forwarding address.
- Webhook URL:
<YOUR BACKEND NGROK ADDRESS>/api/sentry/webhook/ - Redirect URL:
<YOUR FRONTEND NGROK ADDRESS>/sentry/setup/Using the above example, with the python backend, it may look like this: - Webhook URL:
https://backend-py-hostname.ngrok.io/api/sentry/webhook/ - Redirect URL:
https://frontend-hostname.ngrok.io/sentry/setup/
- Webhook URL:
- Ensure 'Verify Installation' is checked.
- Ensure 'Alert Rule Action' is checked.
- In the textbox for 'Schema', paste in the entire
integration-schema.jsonfile - Enable 'Issue & Event - Read' permissions.
- Enable the webhooks
issue(forcreated,resolved,assigned, andignoredactions)comment(forcreated,edited, anddeletedactions)
- Click 'Save Changes'.
- Make a note of the Client ID and Client Secret.
Note: On the free plan for ngrok, if your service restarts, you will be issued a new random forwarding address. If this happens, be sure to update these URLs in Sentry to keep your app functional while developing or testing.
Note: We aren't enabling error.created webhooks for this demo. See more on this decision here.
This demo integration can helpfully create errors in Sentry to trigger webhooks while developing, but you'll need to issue this app a DSN. We'll do this by setting a project.
- Click Projects > Create Project.
- Select React (JS).
- Give your project an appropriate name (for example: Demo Integration).
- Click Create Project.
- Make a note of the DSN URL.
- It is a URL similar to the following if you're using Sentry SaaS:
https://a9d7f6eed0d4883a62ea441b0ea2be81@o456798.ingest.sentry.io/123456
- It is a URL similar to the following if you're using Sentry SaaS:
Next, we'll be taking these values from Sentry and putting together our application's environment.
We've included a .env.sample file for you to refer to when building out your environment. To set it up, change the filename from .env.sample to .env. You can modify any of these variables as you see fit, but the following require changes to work as intended:
SENTRY_CLIENT_ID: The Client ID from Step 2SENTRY_CLIENT_SECRET: The Client Secret from Step 2REACT_APP_SENTRY_DSN: The DSN from Step 2REACT_APP_BACKEND_URL: The ngrok forwarding address of your chosen backend from Step 1
Note: If you change
REACT_APP_PORT,FLASK_RUN_PORT, orEXPRESS_LISTEN_PORT, you may have to reconfigure your ngrok setup and Integration URLs in Sentry
Great, now we're ready to serve our application!
This example code comes with a mock frontend and a choice between two backends, one in NodeJS (Express + TS) and another in Python (Flask). To launch the application, you'll need to install Docker and ensure it is running.
Note: If you are using an M1 Mac, you may encounter an issue building the Python container. Running
export DOCKER_DEFAULT_PLATFORM=linux/amd64prior to building the images should solve the issue. Learn More.
Now you can spin up the project of your choice with:
make serve-python # A python server built on Flask and SQLAlchemy
# OR
make serve-typescript # A typescript node server built on Express and SequelizeThis command will build the Docker images needed to run the application (a Postgres database, a web application, and your chosen backend), and spin them up, all in one step! Once the server logs calm down, your application should be good to go! If you make any changes to the environment variables after this point, be sure to rebuild the images with:
make setup-python
# OR
make setup-typescriptNow the app is ready to test! Continue on to the Using your Integration section to playground your application as you make changes and trigger webhooks in Sentry. There are also some helpful debugging commands which you can check out via:
make helpBuilding an app on our integration platform gives you access to lots of Sentry features. This section will detail how to go about testing them while building your integration.
- How to test installation and uninstallation
installation.created,installation.deleted
- How to test issue webhooks
issue.assigned,issue.created,issue.ignored,issue.resolved
- How to test comment webhooks
comment.created,comment.edited,comment.deleted
- How to test alerting webhooks
event_alert.triggeredmetric_alert.critical,metric_alert.warning,metric_alert.resolved(Requires Team Plan, both to develop and install)
- How to test using the Sentry API
- Using the starter client, refreshing tokens, error handling
Once you've finalized, tested and deployed your application, you can submit a publication request on Sentry. Once it's reviewed, it'll be accessible to install by anyone on the Sentry platform.
Check out the docs to learn more about publishing.
- ui-avatars.com - Simple API to generate initials from names
- Create React App - Scaffold out basic React application to kickstart the project