Sentry

How it works

Sentry Alert Rule Action -> Runframe webhook -> selected Runframe service -> incident

Runframe uses a Sentry App alert rule action. Each Sentry alert rule can choose a Runframe service from the action settings, so one Sentry integration can route alerts to multiple Runframe services.

The current setup uses a Sentry internal integration created inside your Sentry organization. A public Runframe Sentry App is a future path.

Setup from Runframe

1. Go to Integrations Hub.
2. Open Sentry.
3. Link the Runframe services that should receive Sentry alerts.
4. Copy the Webhook URL.
5. Copy the Sentry App JSON.

The webhook URL should look like:

https://runframe.io/api/integrations/sentry/se_12345abcde67890f12345abcde67890f/webhook

The se_... value is your Runframe Sentry integration routing key.

Create the Sentry internal integration

In Sentry:

1. Go to Settings.
2. Open Developer Settings.
3. Create a Custom Integration / Internal Integration.
4. Set Name to Runframe.
5. Set Webhook URL to the Runframe webhook URL.
6. Enable Alert Rule Action.
7. Paste the Sentry App JSON from Runframe into Schema.
8. Leave Authorized JavaScript Origins empty.
9. Save the integration.

Recommended permissions:

Project: Read
Team: No Access
Release: No Access
Distribution: No Access
Issue & Event: Read
Organization: Read
Member: No Access
Alerts: No Access
Continuous Integration (CI): No Access

Leave the broad Webhooks event checkboxes unselected unless you intentionally want non-alert-rule issue/error events to create Runframe incidents.

Sentry App JSON

Use the exact JSON generated by Runframe. It should look like this:

{
  "elements": [
    {
      "uri": "/api/integrations/sentry/se_12345abcde67890f12345abcde67890f/webhook",
      "type": "alert-rule-action",
      "title": "Route to Runframe",
      "settings": {
        "uri": "/api/integrations/sentry/se_12345abcde67890f12345abcde67890f/settings",
        "type": "alert-rule-settings",
        "description": "Choose the Runframe service for alerts from this rule.",
        "required_fields": [
          {
            "name": "service_id",
            "type": "select",
            "label": "Runframe service",
            "options": [
              ["svc_PROD12345", "Production API"],
              ["svc_CHECKOUT1", "Checkout"],
              ["svc_INFRA6789", "Internal Infrastructure"]
            ]
          }
        ]
      }
    }
  ]
}

Do not manually change the service IDs unless you are debugging a known Runframe service key. The Runframe UI generates the correct values from linked services.

Configure a Sentry alert rule

After saving the internal integration, add Runframe to an alert rule.

1. Go to Alerts in Sentry.
2. Create or edit an issue alert.
3. Under Source, select the Sentry projects that should route alerts to Runframe.
4. Choose Alert on all issues in selected projects, unless you intentionally want monitor-specific routing.
5. Under Filter Issues, choose the environments that should create Runframe incidents.
6. In Alert Builder, configure the trigger. For example:

When an issue event is captured and any of the following occur:
A new issue is created

7. Add the action Route to Runframe.
8. In Action Settings, select the target Runframe service.
9. Click Send Test Notification and confirm Runframe creates an incident for the selected service.
10. Set Action Throttle, for example 24 hours.
11. Save the alert rule.

The important part is that the Runframe service is selected inside the Sentry alert action. Sentry sends that value to Runframe as service_id when the alert fires.

Field mapping

Severity mapping

Configure how Sentry levels map to Runframe incident actions:

Deduplication

Runframe derives a stable deduplication key from the Sentry issue or event identifiers when available. Repeated events update the same open incident instead of creating duplicates.

Troubleshooting

Sentry says 'uri' is a required property

The top-level alert-rule-action element must include uri. Having only settings.uri is not enough.

Sentry says 'elements' is a required property

Paste the full JSON object from Runframe, including the top-level elements array.

Sentry says alert-rule-settings is not an allowed top-level type

alert-rule-settings must be nested under the settings property of an alert-rule-action.

Sentry succeeds but Runframe does not create an incident

Check the Runframe integration event logs.

Common reasons:

• The alert rule did not include a service_id.
• The selected service is not linked to this Runframe Sentry integration.
• The Sentry payload did not include an issue or event body.

Testing

Use Send Test Notification in the Sentry alert rule and verify:

1. Runframe creates the incident
2. Title, severity, and service routing are correct
3. Sentry context is attached
4. The right team is notified