Skip to main content
The Sentry Developer Platform lets you build custom integrations on top of Sentry. You can create internal integrations for your own organization or published Sentry Apps that are available to all Sentry users.

​
Internal integrations vs. published apps

Internal integrations are private to your Sentry organization. They are the fastest way to build a custom workflow, automation, or data pipeline on top of Sentry.Use cases:
  • Receive webhooks for Sentry events and trigger custom workflows
  • Create UI components that appear in the Sentry issue detail sidebar
  • Automate issue triage or routing based on error data

​
What Sentry Apps can do

Webhooks

Subscribe to events (issues, errors, comments, alerts) and receive HTTP POST requests to your endpoint.

Issue link component

Add a custom Link Issue button to the Sentry issue sidebar that opens a modal in your app.

Stacktrace link component

Map stack frames to URLs in your system for code navigation.

Alert rule action

Add a custom action type to Sentry alert rules so users can trigger workflows in your app.

OAuth

Use standard OAuth 2.0 to authenticate users in your app with their Sentry identity.

Service hooks

Receive HTTP webhooks for raw Sentry events scoped to specific projects.

​
Creating a Sentry App

1

Open the developer settings

In Sentry, go to Settings > Developer Settings. Click Create New Internal Integration or Create New Public Integration.
2

Fill in the basic information

Provide:
  • Name: The display name of your integration.
  • Webhook URL: The HTTPS endpoint where Sentry will send webhook payloads.
  • Redirect URL: The OAuth callback URL (required for public apps or if using OAuth).
  • Schema: A JSON schema defining the UI components your app provides (optional).
3

Set permissions

Select the scopes your app needs. Scopes control what data your app can read or write via the Sentry API. Common scopes include:
ScopeAccess
event:readRead events and issues
event:writeUpdate issue status and assignments
project:readRead project configuration
org:readRead organization data
member:readRead member information
4

Subscribe to webhook events

Select the event resources your app should receive webhooks for:
ResourceEvents
Issueissue.created, issue.resolved, issue.ignored, issue.assigned, issue.unresolved
Errorerror.created
Commentcomment.created, comment.updated, comment.deleted
Installationinstallation.created, installation.deleted
Metric alertmetric_alert.open, metric_alert.resolved, metric_alert.critical, metric_alert.warning
Issue alertevent_alert.triggered
5

Add UI components (optional)

Define UI components in the Schema field using JSON. See the UI components section below for details.
6

Install and get credentials

After saving, install the app on your organization. Sentry generates a client ID and client secret (for public apps) or an API token (for internal integrations).

​
OAuth flow

Published Sentry Apps use OAuth 2.0 to authenticate users. 
1. Redirect user to:
   https://sentry.io/oauth/authorize/?response_type=code&client_id=YOUR_CLIENT_ID

2. User authorizes your app.

3. Sentry redirects to your redirect_url with ?code=AUTH_CODE

4. Exchange code for token:
   POST https://sentry.io/api/0/sentry-app-installations/{uuid}/authorizations/
   Body: { grant_type: "authorization_code", code: "AUTH_CODE", client_secret: "YOUR_SECRET" }

5. Sentry returns access_token and refresh_token.

​
Webhook event types

Sentry sends webhook payloads as HTTP POST requests to your configured endpoint. Each payload includes a action and data field.

​
Issue events

{
  "action": "created",
  "installation": { "uuid": "..." },
  "data": {
    "issue": {
      "id": "123",
      "title": "TypeError: Cannot read property 'foo' of undefined",
      "status": "unresolved",
      "project": { "id": "1", "slug": "my-project" }
    }
  },
  "actor": { "type": "user", "id": "456", "name": "Jane Smith" }
}

​
Error events

{
  "action": "created",
  "installation": { "uuid": "..." },
  "data": {
    "error": {
      "event_id": "abc123",
      "message": "TypeError: Cannot read property 'foo' of undefined",
      "level": "error",
      "project": "my-project"
    }
  }
}

​
HMAC signature verification

Sentry signs webhook payloads with an HMAC-SHA256 signature so you can verify the request came from Sentry. The signature is in the sentry-hook-signature HTTP header. 
import hmac
import hashlib

def verify_signature(secret: str, payload: bytes, signature: str) -> bool:
    expected = hmac.new(
        key=secret.encode("utf-8"),
        msg=payload,
        digestmod=hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
Always verify the HMAC signature before processing webhook payloads to prevent spoofed requests.

​
UI components

Adds a Link [App Name] Issue button to the Sentry issue sidebar. When clicked, it opens a modal defined by your schema. 
{
  "elements": [
    {
      "type": "issue-link",
      "link": {
        "uri": "/link-issue",
        "required_fields": [
          {
            "type": "select",
            "label": "Issue",
            "name": "issue_id",
            "uri": "/search-issues"
          }
        ]
      },
      "create": {
        "uri": "/create-issue",
        "required_fields": [
          {
            "type": "text",
            "label": "Title",
            "name": "title"
          }
        ]
      }
    }
  ]
}
Maps Sentry stack frames to URLs in your system. 
{
  "elements": [
    {
      "type": "stacktrace-link",
      "uri": "/stacktrace-redirect"
    }
  ]
}
Sentry calls your uri with query parameters including lineNo, filename, and absPath.

​
Alert rule action component

Adds a custom action type to Sentry alert rules. 
{
  "elements": [
    {
      "type": "alert-rule-action",
      "title": "Notify My Service",
      "settings": {
        "type": "alert-rule-settings",
        "uri": "/alert-rule-action",
        "required_fields": [
          {
            "type": "text",
            "label": "Channel",
            "name": "channel"
          }
        ]
      }
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us