Internal Integration Setup
Connect a single Sentry organization to BlameTrail using an internal integration with manual token configuration.
An internal Sentry integration is the simplest way to connect Sentry to BlameTrail. It works well for teams that use a single Sentry organization and prefer manual token management over OAuth.
Prerequisites
- A Sentry organization with admin or manager permissions
- A BlameTrail organization with admin access
Step 1: Create the internal integration in Sentry
- In Sentry, go to Settings > Developer Settings.
- Click Create New Integration and select Internal Integration.
- Fill in the details:
| Field | Value |
|---|---|
| Name | BlameTrail |
| Webhook URL | https://blametrail.com/api/integrations/sentry/webhook |
- Set the following permissions:
| Permission | Access level |
|---|---|
| Project | Read |
| Issue & Event | Read |
| Organization | Read |
-
Under Webhooks, enable the events you want to forward:
- Issue — Created, resolved, assigned, archived
- Error — New error events
- Alert Rule — Alert rule actions (if using alert rule integration)
-
Click Save Changes.
Step 2: Copy credentials from Sentry
After saving, Sentry displays the integration details. Copy the following:
- Auth Token — The token BlameTrail uses to call the Sentry API for enrichment
- Client Secret — Used to verify incoming webhook signatures (HMAC)
Store both values securely. You will enter them in BlameTrail in the next step.
Step 3: Connect in BlameTrail
- In BlameTrail, navigate to Organization > Integrations.
- Find the Sentry section and click Connect.
- Enter the following:
| Field | Description |
|---|---|
| Organization Slug | Your Sentry organization slug (found in your Sentry URL: sentry.io/organizations/{slug}/) |
| Auth Token | The auth token from Step 2 |
| Client Secret | The client secret from Step 2 (used for HMAC webhook verification) |
- Click Save.
BlameTrail verifies the token by making a test API call to Sentry. If the connection succeeds, the integration status changes to Connected.
Step 4: Set up project mappings
Before Sentry webhooks can create incidents in BlameTrail, you need to map Sentry projects to BlameTrail services. See Project Mappings for instructions.
Without mappings, incoming webhooks from unmapped projects are ignored.
Step 5: Test the integration
- In your Sentry project, trigger a test error (e.g., throw an unhandled exception in your application).
- Verify that the Sentry issue webhook is delivered by checking Settings > Developer Settings > BlameTrail > Webhooks in Sentry.
- In BlameTrail, check the mapped service's incidents list. A new incident should appear with Sentry enrichment data (tags, stacktrace, event details).
Token management
Internal integration tokens do not expire. However, if you regenerate the token in Sentry, you must update it in BlameTrail:
- Go to Organization > Integrations > Sentry.
- Update the Auth Token field with the new token.
- Click Save.
Webhook verification uses the Client Secret, which is separate from the auth token. If you regenerate the client secret in Sentry, update it in BlameTrail as well.
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| Connection test fails | Incorrect org slug or token | Verify the org slug matches your Sentry URL and the token is copied correctly |
| Webhooks return 401 | Client secret mismatch | Ensure the client secret in BlameTrail matches the one in Sentry |
| No incidents created | Project not mapped | Add a project mapping in Organization > Integrations > Sentry > Project Mappings |
| Enrichment data missing | Insufficient permissions | Verify the integration has Read access for Project, Issue & Event, and Organization |