Sentry integration#

IncidentRelay can receive signed webhooks from Sentry Internal Integrations and turn Sentry issue alerts, metric alerts and issue lifecycle events into IncidentRelay alerts.

The Sentry integration is route-scoped: every Sentry route has its own webhook URL and its own Sentry webhook secret. The secret is stored in the route integration settings and is never returned by the API.

Supported Sentry events#

IncidentRelay supports the following Sentry webhook resources:

For issue alerts, IncidentRelay uses the Sentry issue id as the deduplication key. This allows a later issue.resolved event to resolve the same IncidentRelay alert that was created by event_alert.triggered.

Before you start#

You need:

• an IncidentRelay team and route management permissions;
• a public HTTPS URL for IncidentRelay that Sentry can reach;
• Sentry organization admin or manager permissions to create an Internal Integration;
• the full Sentry integration implementation deployed, including the integration_config migration.

Do not use the legacy Sentry Webhook Plugin for this integration. Use a Sentry Internal Integration because IncidentRelay verifies the Sentry-Hook-Signature header sent by Internal Integration webhooks.

Step 1: Create a Sentry route in IncidentRelay#

Open Routes and create a new route:

"project_slug", "issue_id" ]` for issue alerts | | Matchers | Optional labels matcher, for example by project or environment | | Enabled | On |

Example matchers:

Copy{
  "labels": {
    "project_slug": "backend-api",
    "environment": "production"
  }
}

Recommended group by for issue alerts:

Copy["project_slug", "issue_id"]

Recommended group by for metric alerts:

Copy["project_slug", "sentry_alert_id"]

After the route is created, IncidentRelay shows a webhook URL similar to:

Copyhttps://incidentrelay.example.com/api/integrations/sentry/42

Copy this URL. You will paste it into Sentry.

At this stage the route can exist without a Sentry secret. Incoming Sentry webhooks will be rejected until the secret is configured.

Step 2: Create a Sentry Internal Integration#

In Sentry, open organization settings and create an Internal Integration.

Configure:

Enable webhook resources needed by your alerting flow:

• event_alert for Sentry issue alert rules;
• metric_alert for Sentry metric alert rules and metric recovery events;
• issue for resolve, ignored and reopened lifecycle events.

Save the Sentry Internal Integration.

Step 3: Copy the Sentry Client Secret into IncidentRelay#

After creating the Internal Integration, Sentry shows integration credentials.

Copy the Client Secret and paste it into the IncidentRelay route:

• Open the Sentry route in IncidentRelay.
• Click Edit.
• Paste the value into Sentry webhook secret.
• Save the route.

IncidentRelay stores the secret in route.integration_config.sentry.webhook_secret and uses it to verify incoming webhooks.

The API will only expose:

Copy{
  "integration_config": {
    "sentry": {
      "has_webhook_secret": true,
      "webhook_path": "/api/integrations/sentry/42"
    }
  }
}

It will not return the raw secret.

Step 4: Add IncidentRelay to Sentry alert rules#

Create or edit Sentry alert rules.

For issue alerts:

• Open the Sentry project.
• Go to Alerts.
• Create or edit an issue alert rule.
• In the actions section, select the IncidentRelay integration action.
• Save the rule.

For metric alerts:

• Open the Sentry project.
• Go to Alerts.
• Create or edit a metric alert rule.
• Select the IncidentRelay integration action.
• Save the rule.

When a Sentry alert rule fires, Sentry sends a signed webhook to IncidentRelay. IncidentRelay verifies the signature and normalizes the event into an internal alert.

How routing works#

Sentry events are normalized with source=sentry and labels such as:

Copy{
  "alertname": "SentryIssueAlert",
  "sentry_resource": "event_alert",
  "sentry_action": "triggered",
  "organization_slug": "acme",
  "project_slug": "backend-api",
  "project_name": "Backend API",
  "issue_id": "12345",
  "issue_short_id": "BACKEND-1",
  "event_id": "event-abc",
  "environment": "production",
  "level": "error",
  "sentry_url": "https://sentry.example.com/issues/12345/"
}

You can route by any of these labels.

Common matcher examples:

Route only production alerts from a project:

Copy{
  "labels": {
    "project_slug": "backend-api",
    "environment": "production"
  }
}

Route any production Sentry alert:

Copy{
  "labels": {
    "environment": "production"
  }
}

Route only metric alerts:

Copy{
  "labels": {
    "sentry_resource": "metric_alert"
  }
}

Deduplication and resolve behavior#

Issue alerts use:

Copysentry:issue:<issue_id>

Metric alerts use:

Copysentry:metric:<sentry_alert_id>

This means:

• repeated Sentry issue alert triggers update the same IncidentRelay alert;
• issue.resolved resolves the existing IncidentRelay alert for the same issue;
• metric_alert.resolved resolves the existing metric alert;
• Sentry issue and metric payloads can use different resources while still resolving the correct alert.

Security model#

Sentry webhooks do not use an IncidentRelay intake token.

Instead, IncidentRelay verifies:

• route id from the URL: /api/integrations/sentry/{route_id};
• route source is sentry;
• route and team are enabled;
• Sentry-Hook-Signature matches the request body and the route's Sentry Client Secret.

If the secret is missing or invalid, the webhook is rejected.

References#

• Sentry Integration Platform: https://docs.sentry.io/integrations/integration-platform/
• Sentry webhooks: https://docs.sentry.io/integrations/integration-platform/webhooks/
• Sentry issue alert webhooks: https://docs.sentry.io/integrations/integration-platform/webhooks/issue-alerts/
• Sentry alert rule action component: https://docs.sentry.io/integrations/integration-platform/ui-components/alert-rule-action/