Project Mappings

Project mappings tell BlameTrail which Sentry project corresponds to which BlameTrail service. When a Sentry webhook arrives, BlameTrail checks the project slug against your mappings and creates the incident on the mapped service. Webhooks from unmapped projects are ignored.

Why mappings are required

Sentry organizes errors by project (e.g., frontend, payments-api, worker). BlameTrail organizes monitoring by service. These may not have a one-to-one naming relationship, so explicit mappings are needed to route Sentry events to the correct service.

Without at least one mapping, Sentry webhooks will be received but no incidents will be created.

Adding a mapping

1. Navigate to Organization > Integrations > Sentry.
2. Click Project Mappings (or scroll to the Project Mappings section).
3. Click Add Mapping.
4. Select or enter the Sentry project slug — the project identifier from your Sentry URL (e.g., payments-api from sentry.io/organizations/acme/projects/payments-api/).
5. Select the BlameTrail service to receive incidents from this Sentry project.
6. Click Save.

Managing mappings

Enable or disable a mapping

Each mapping has an active/inactive toggle. When a mapping is disabled:

• Webhooks from that Sentry project are still received but not processed.
• No incidents are created for events from the disabled project.
• The mapping configuration is preserved and can be re-enabled at any time.

This is useful for temporarily pausing Sentry-to-BlameTrail incident creation during maintenance windows or noisy periods.

Editing a mapping

To change which BlameTrail service a Sentry project maps to:

1. Find the mapping in the Project Mappings list.
2. Click Edit.
3. Select a different BlameTrail service.
4. Click Save.

Existing incidents created under the old mapping are not moved. Only new webhooks will route to the updated service.

Deleting a mapping

To permanently remove a mapping:

1. Find the mapping in the Project Mappings list.
2. Click Delete.
3. Confirm the deletion.

After deletion, webhooks from that Sentry project will be ignored until a new mapping is created.

Multiple mappings

You can create as many mappings as needed:

• One Sentry project to one BlameTrail service — The standard configuration. Each Sentry project maps to exactly one service.
• Multiple Sentry projects to one BlameTrail service — Useful if you have several Sentry projects that represent parts of the same service (e.g., api-auth and api-core both mapping to an API service in BlameTrail).

Each Sentry project can only be mapped to one BlameTrail service at a time.

Unmapped projects

When BlameTrail receives a webhook for a Sentry project that has no active mapping:

• The webhook is acknowledged with a 200 response (so Sentry does not retry).
• No incident is created.
• The event is logged for auditing purposes.

This is intentional — it allows you to connect Sentry at the organization level while selectively routing only the projects you care about.

Example configuration

In this example, Sentry events from frontend, payments-api, and email-worker create incidents in BlameTrail. Events from internal-tools are received but not processed because the mapping is inactive.