{"id":26452963,"url":"https://github.com/getsentry/integration-platform-example","last_synced_at":"2025-03-18T18:40:50.828Z","repository":{"id":38833841,"uuid":"458291879","full_name":"getsentry/integration-platform-example","owner":"getsentry","description":"An example kanban application which explores the ways developers can build apps on Sentry's integration platform","archived":false,"fork":false,"pushed_at":"2024-07-02T17:27:30.000Z","size":1862,"stargazers_count":64,"open_issues_count":2,"forks_count":37,"subscribers_count":39,"default_branch":"main","last_synced_at":"2025-03-13T01:17:23.788Z","etag":null,"topics":["demo","integration","sentry","tag-non-production"],"latest_commit_sha":null,"homepage":"https://docs.sentry.io/product/integrations/integration-platform/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getsentry.png","metadata":{"funding":{"custom":["https://sentry.io/pricing/","https://sentry.io/"]},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-11T18:07:17.000Z","updated_at":"2025-02-20T17:57:15.000Z","dependencies_parsed_at":"2024-05-28T18:46:23.196Z","dependency_job_id":"d052cc44-81dd-434c-8723-268498416baa","html_url":"https://github.com/getsentry/integration-platform-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fintegration-platform-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fintegration-platform-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fintegration-platform-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fintegration-platform-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getsentry","download_url":"https://codeload.github.com/getsentry/integration-platform-example/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244282969,"owners_count":20428103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["demo","integration","sentry","tag-non-production"],"created_at":"2025-03-18T18:40:50.233Z","updated_at":"2025-03-18T18:40:50.820Z","avatar_url":"https://github.com/getsentry.png","language":"TypeScript","readme":"# Integration Platform Example\n\nSo you want to integrate with the [Sentry Integration Platform](https://docs.sentry.io/product/integrations/integration-platform/). Great! We're looking forward to it 🎉\nThat's why we built out this codebase; clone and fork away!\n\nThis 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.\n\n![Kanban application user interface](./docs/reference-implementation-frontend.png)\n\nIn it, we'll be covering the following features:\n\n- Handling Installation (with OAuth)\n- Using the [Sentry API](https://docs.sentry.io/api/)\n- Verifying Installations\n- Handling Uninstallations\n- Handling Webhooks\n  - Issues\n  - Comments\n  - Alerts\n- Implementing UI Components\n  - Issue Linking\n  - Alert Rule Actions\n\nIf we missed something, or you're still having trouble, feel free to [create an issue](https://github.com/sentry-ecosystem/integration-platform-example/issues), and we'll see what we can do! Happy Developing!\n\n\u003c!--\nAutogenerated via VSCode Extension: Markdown All in One\nTo maintainers: If this becomes annoying to maintain, feel free to remove it!\n--\u003e\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Step 0: Choose an Integration](#step-0-choose-an-integration)\n  - [Step 1: Setup ngrok](#step-1-setup-ngrok)\n  - [Step 2: Setup Sentry](#step-2-setup-sentry)\n  - [Step 3: Setup your environment](#step-3-setup-your-environment)\n  - [Step 4: Build and serve the codebase](#step-4-build-and-serve-the-codebase)\n- [Using your Integration](#using-your-integration)\n  - [Webhooks](#webhooks)\n  - [UI Components](#ui-components)\n  - [API Usage](#api-usage)\n- [Publishing](#publishing)\n- [Credits](#credits)\n\n## Getting Started\n\n### Prerequisites\n\n- [**Sentry**](https://sentry.io) - You must be either a Manager or Owner of an organization on Sentry.\n- [**Docker**](https://docs.docker.com/get-docker/) - This demo application uses Docker to setup and communicate between its different services.\n- **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!\n- **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.\n- **A local PostgreSQL DB Client** (Optional) - Great for viewing changes on objects, and debugging, removing, or editing data. We suggest [Postico](https://eggerapps.at/postico/).\n\n### Step 0: Choose an Integration\n\nBefore setting anything up, you must determine the type of integration you're building on Sentry's [Integration Platform](https://docs.sentry.io/product/integrations/integration-platform/).\n\n[Public integrations](https://docs.sentry.io/product/integrations/integration-platform/public-integration) are meant to be accessed by all Sentry Customers, regardless of whether or not they belong to your organization.\n\nIf you only wish to provide an application to your team or organization, you should probably develop an [Internal integration](https://docs.sentry.io/product/integrations/integration-platform/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.\n\nThis tutorial assumes you're building a public integration, but most of the steps are identical for internal integrations unless stated otherwise.\n\n### Step 1: Setup ngrok\n\nTo get started, you'll need access to [ngrok](https://ngrok.com/). 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](https://ngrok.com/download).\n\nMake sure [you add an authtoken](https://ngrok.com/docs/ngrok-agent/ngrok#command-ngrok-config-add-authtoken) in order to generate a [configuration file](https://ngrok.com/docs/ngrok-agent/config).\n\nCopy the included [`ngrok-config.example.yml`](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](https://dashboard.ngrok.com/cloud-edge/domains) settings page on paid plans.\n\nThis will let you easily set up your tunnels with:\n\n```shell\nngrok start --all --config ngrok-config.yml\n```\n\nWith ngrok running, you'll be presented with an interface that might look like the following:\n\n```text\nngrok\n\nSession Status      online\nAccount             Sentry (Plan: Pro)\nVersion             3.0.3\nRegion              United States (us)\nLatency             96.595653ms\nWeb Interface       http://127.0.0.1:4040\nForwarding          https://frontend-hostname.ngrok.io -\u003e http://localhost:3000\nForwarding          https://backend-py-hostname.ngrok.io -\u003e http://localhost:5100\nForwarding          https://backend-ts-hostname.ngrok.io -\u003e http://localhost:5200\n\nConnections         ttl     opn     rt1     rt5     p50     p90\n                    0       0       0.00    0.00    0.00    0.00\n```\nTake 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:\n\n```text\n[Frontend address]           -\u003e http://localhost:3000\n[Python backend address]     -\u003e http://localhost:5100\n[Typescript backend address] -\u003e http://localhost:5200\n```\n\nThough, if you change your [environment variables in Step 3](#step-3-setup-your-environment), from their default values, this will not be the case.\n\n### Step 2: Setup Sentry\n\nNext, 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.\n\n1. Click Settings \u003e Developer Settings \u003e Create New Integration \u003e Public Integration\n2. Give your integration an appropriate name and author.\n3. Specify a Webhook and Redirect URL with your ngrok forwarding address.\n   - Webhook URL: `\u003cYOUR BACKEND NGROK ADDRESS\u003e/api/sentry/webhook/`\n   - Redirect URL: `\u003cYOUR FRONTEND NGROK ADDRESS\u003e/sentry/setup/`\n     Using the above example, with the python backend, it may look like this:\n   - Webhook URL: `https://backend-py-hostname.ngrok.io/api/sentry/webhook/`\n   - Redirect URL: `https://frontend-hostname.ngrok.io/sentry/setup/`\n4. Ensure 'Verify Installation' is checked.\n5. Ensure 'Alert Rule Action' is checked.\n6. In the textbox for 'Schema', paste in the entire [`integration-schema.json` file](integration-schema.json)\n7. Enable 'Issue \u0026 Event - Read' permissions.\n8. Enable the webhooks\n   - `issue` (for `created`, `resolved`, `assigned`, and `ignored` actions)\n   - `comment` (for `created`, `edited`, and `deleted` actions)\n9. Click 'Save Changes'.\n10. Make a note of the **Client ID** and **Client Secret**.\n\n**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.\n\n**Note**: We aren't enabling `error.created` webhooks for this demo. See more on this decision [here](docs/webhooks/event-webhooks.md#error-webhooks).\n\nThis 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.\n\n1. Click Projects \u003e Create Project.\n2. Select React (JS).\n3. Give your project an appropriate name (for example: Demo Integration).\n4. Click Create Project.\n5. Make a note of the **DSN** URL.\n   - It is a URL similar to the following if you're using Sentry SaaS:\n     `https://a9d7f6eed0d4883a62ea441b0ea2be81@o456798.ingest.sentry.io/123456`\n\nNext, we'll be taking these values from Sentry and putting together our application's environment.\n\n### Step 3: Setup your environment\n\nWe'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:\n\n- `SENTRY_CLIENT_ID`: The Client ID from Step 2\n- `SENTRY_CLIENT_SECRET`: The Client Secret from Step 2\n- `REACT_APP_SENTRY_DSN`: The DSN from Step 2\n- `REACT_APP_BACKEND_URL`: The ngrok forwarding address of your chosen backend from Step 1\n\n\u003e Note: If you change `REACT_APP_PORT`, `FLASK_RUN_PORT`, or `EXPRESS_LISTEN_PORT`, you may have to reconfigure your ngrok setup and Integration URLs in Sentry\n\nGreat, now we're ready to serve our application!\n\n### Step 4: Build and serve the codebase\n\nThis 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](https://docs.docker.com/engine/install/) and ensure it is running.\n\n\u003e Note: If you are using an M1 Mac, you may encounter an [issue](https://github.com/getsentry/integration-platform-example/issues/48) building the Python container. Running `export DOCKER_DEFAULT_PLATFORM=linux/amd64` prior to building the images should solve the issue. [Learn More](https://stackoverflow.com/questions/62807717/how-can-i-solve-postgresql-scram-authentifcation-problem).\n\nNow you can spin up the project of your choice with:\n\n```bash\nmake serve-python # A python server built on Flask and SQLAlchemy\n# OR\nmake serve-typescript # A typescript node server built on Express and Sequelize\n```\n\nThis 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:\n\n```bash\nmake setup-python\n# OR\nmake setup-typescript\n```\n\nNow the app is ready to test! Continue on to the [Using your Integration](#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:\n\n```bash\nmake help\n```\n\n## Using your Integration\n\nBuilding 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.\n\n### Webhooks\n\n- [How to test installation and uninstallation](/docs/installation.md)\n  - `installation.created`, `installation.deleted`\n- [How to test issue webhooks](/docs/webhooks/event-webhooks.md#issue-webhooks)\n  - `issue.assigned`, `issue.created`, `issue.ignored`, `issue.resolved`\n- [How to test comment webhooks](/docs/webhooks/comment-webhooks.md)\n  - `comment.created`, `comment.edited`, `comment.deleted`\n- [How to test alerting webhooks](/docs/webhooks/alert-webhooks.md)\n  - `event_alert.triggered`\n  - `metric_alert.critical`, `metric_alert.warning`, `metric_alert.resolved` _(Requires Team Plan, both to develop and install)_\n\n### UI Components\n\n- [How to test Issue Linking](/docs/ui-components/issue-linking.md)\n- [How to test Alert Rule UI Components](/docs/ui-components/alert-rule-actions.md)\n\n### API Usage\n\n- [How to test using the Sentry API](/docs/api-usage.md)\n  - Using the starter client, refreshing tokens, error handling\n\n## Publishing\n\nOnce 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.\n\nCheck out [the docs](https://docs.sentry.io/product/integrations/integration-platform/public-integration/#publication) to learn more about publishing.\n\n## Credits\n\n- [ui-avatars.com](https://ui-avatars.com/) - Simple API to generate initials from names\n- [Create React App](https://create-react-app.dev/) - Scaffold out basic React application to kickstart the project\n","funding_links":["https://sentry.io/pricing/","https://sentry.io/"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fintegration-platform-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetsentry%2Fintegration-platform-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fintegration-platform-example/lists"}