Sentry

What your agents can doCopy Anchor Link

Helios agents call Sentry's REST API using the connected integration's permissions. They can read and update issues, events, projects, releases, and alerts.

• Find the newest or most frequent issues in a project or release and summarize them
• Read an issue's events, stack trace, breadcrumbs, and tags, and suggest a fix
• Resolve, archive, assign, or delete issues, and change their priority
• Read an issue's comments and reply to them
• Create releases and deploys, and manage alerts, monitors, projects, and teams

Sentry's published spec doesn't include issue comments, so Helios describes them from Sentry's source. Agents can list and add comments, and change or delete comments that the integration wrote. Agents can only reach the Sentry server set on the connection.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Both methods have the same prerequisites:

• Role: you need the Owner role to give the integration every permission below. Sentry doesn't let you give an integration more permissions than your own, and only Owners have Organization: Admin. A Manager can set everything else. Sentry shows an integration's credentials only to Owners and Managers.
• Plan: Sentry's pricing page lists the API and alerts through integrations on the Team plan and higher. Error webhooks need the Business plan or higher.

Helios calls https://sentry.io by default, which works for organizations in both the US and the EU (DE) region. To use the region's own address or a self-hosted Sentry, fill in Base URL, below the method's fields, when you connect. Enter https://de.sentry.io or your server's address, such as https://sentry.example.com, without /api/0. The address must use https and must not be localhost or a private network address. Leave it empty to use https://sentry.io. To change the base URL later, enter the Auth Token or Client Secret again.

PermissionsCopy Anchor Link

Both methods get the permissions you set on the integration in Sentry. Helios doesn't request scopes of its own. Set each permission to the level below, for the operations described below:

The Admin levels of Project, Team, Issue & Event, Organization, and Member only add the delete endpoints. Choose Read & Write for any of them if agents shouldn't delete in that area. Webhooks also need at least Read on Issue & Event for issue, error, comment, and Seer events, and on Project for mobile build events.

Sentry Auth TokenCopy Anchor Link

1. In Sentry, open Settings → Developer Settings → Custom Integrations. Click Create New Integration, choose Internal Integration, and click Get started.
2. Name it Helios. Leave Webhook URL empty for now.
3. Under Permissions, set every permission as in the table above, and select Continuous Integration (CI).
4. Click Save Changes. Copy the token under Tokens, and the Client Secret under Credentials. Sentry shows the client secret only briefly after you create the integration. You need it for triggers.
5. In Helios, choose Sentry Auth Token. Paste the token into Auth Token, and enter your organization's slug, such as acme in acme.sentry.io, in Organization Slug.
6. Save.

Internal integration tokens don't expire. If you revoke the token, create a new one under Tokens and enter it in Helios through Manage.

Your own Sentry OAuth appCopy Anchor Link

This method connects through a public integration that you create. It can stay unpublished, because only your organization installs it.

1. In Sentry, open Settings → Developer Settings → Custom Integrations. Click Create New Integration, choose Public Integration, and click Get started.

2. Fill in Name and Author. Set Redirect URL to:

   Copy Text

   https://api.heliosapp.com/integrations/sentry/oauth_callback

3. Sentry requires a Webhook URL for public integrations. Use this until you connect:

   Copy Text

   https://api.heliosapp.com/integrations/sentry/webhooks/pending

4. Leave Verify Installation off. Under Permissions, set every permission as in the table above, and select Continuous Integration (CI). Click Save Changes.

5. Copy the integration's slug from its URL in Developer Settings, and the Client ID and Client Secret under Credentials. Sentry shows the client secret only briefly after you create the integration.

6. In Helios, choose Your own Sentry OAuth app. Enter the slug in Integration Slug, and fill in Client ID and Client Secret.

7. Save. Sentry shows the integration's permissions and asks you to install it in your organization. If it's already installed, uninstall it in Sentry first.

Helios gets the organization from the installation, so this method has no organization field. Sentry's tokens expire after eight hours, and Helios refreshes them with the client secret. Helios also saves the client secret as the webhook secret, because Sentry signs webhooks with it.

If you rotate the client secret, enter the new one in Helios through Manage. After that, or after you change the integration's permissions, uninstall the integration in Sentry and connect again.

When you delete the connection in Helios, Helios also uninstalls the integration in Sentry. This needs Organization set to Read & Write or Admin. If the uninstall fails, Helios still deletes the connection, and you can uninstall the integration in Sentry yourself.

TriggersCopy Anchor Link

Sentry can start a Workflow when something happens in your organization. Sentry sets an integration's webhook URL and events only in its own settings, so you set them up by hand. Events come from the integration you connected: the internal integration for Sentry Auth Token, or the public integration for Your own Sentry OAuth app.

Each integration sends webhooks to one URL. A Helios connection that needs triggers needs its own integration in Sentry.

With Sentry Auth TokenCopy Anchor Link

1. In Helios, open the Sentry connection, click Manage, and open Advanced Configuration. Under Webhook Setup, paste the internal integration's Client Secret into the secret field and save. Then copy the webhook URL.
2. In Sentry, open the internal integration under Settings → Developer Settings → Custom Integrations.
3. Paste the URL into Webhook URL and turn on Alert Action.
4. Under Webhooks, select every event. Select the Issues, Errors, Comments, Seer, and Preprod Artifacts boxes. Each box selects all of its events.
5. Click Save Changes.

With your own Sentry OAuth appCopy Anchor Link

Helios has already saved the client secret as the webhook secret.

1. In Helios, open the Sentry connection, click Manage, and open Advanced Configuration. Copy the URL under Webhook Setup.
2. In Sentry, open the public integration under Settings → Developer Settings → Custom Integrations.
3. Replace the pending Webhook URL with the copied URL, and turn on Alert Action.
4. Under Webhooks, select every event. Select the Issues, Errors, Comments, Seer, and Preprod Artifacts boxes. Each box selects all of its events.
5. Click Save Changes.

Sentry sends installation events only to public integrations. installation.deleted arrives when the integration is uninstalled, and Helios then marks the connection Disconnected. installation.created arrives only when the integration is installed after its Webhook URL points at Helios, such as when you reinstall it.

If the Errors box can't be selected, your Sentry plan doesn't include error webhooks.

AlertsCopy Anchor Link

Issue, error, comment, Seer, mobile build, and installation events arrive once the webhook is set up. Alert events arrive only from Sentry Alerts that send a notification through the integration you connected.

1. In Sentry, go to Monitors → Alerts and click Create Alert.
2. Choose the source. To be alerted by a Metric Monitor, choose Alert on specific monitors and connect it.
3. Under When, choose the triggers. Triggers on issue activity, such as An issue is resolved or Seer runs on an issue and reaches the stage..., send activity_alert.triggered. The others send issue_alert.triggered.
4. Under Then, add Send a notification via an integration and choose the integration you connected to Helios. If the integration has the schema for metric alerts, add its own action instead. With Your own Sentry OAuth app, choose the public integration, not an internal one.
5. Click Create Alert.

To use an existing Alert, edit it and add the same action.

A Metric Monitor's Alert also arrives as these two events. issue_alert.triggered arrives when the monitor opens an issue, and activity_alert.triggered arrives when the issue resolves, if the Alert triggers on An issue is resolved. For metric_alert.triggered and metric_alert.resolved, set up the integration's own action as described below.

Metric alertsCopy Anchor Link

Sentry sends metric_alert.triggered and metric_alert.resolved only through an integration's own Alert action. The integration gets that action when its schema has an alert rule action.

1. In Helios, open the Sentry connection, click Manage, and copy the webhook URL under Webhook Setup. The last part of the URL is the connection's ID.

2. In Sentry, open the integration under Settings → Developer Settings → Custom Integrations, and check that Alert Action is on.

3. Paste this into Schema. Replace <connection ID> with the connection's ID.

   Copy Text

   {
     "elements": [
       {
         "type": "alert-rule-action",
         "title": "Helios",
         "settings": {
           "type": "alert-rule-settings",
           "uri": "/integrations/sentry/webhooks/<connection ID>?alert-rule-action=1",
           "required_fields": [
             {
               "type": "select",
               "name": "target",
               "label": "Send to",
               "options": [["workflows", "Helios workflows"]]
             }
           ]
         }
       }
     ]
   }

   If an existing schema uses /integrations/sentry/alert-rule-action/<connection ID>, replace its uri with the webhook path and query string shown above before saving an Alert.

4. Click Save Changes.

5. In the Metric Monitor's Alert, under Then, add the action named after the integration, and choose Helios workflows in Send to. Save the Alert. Sentry asks Helios to confirm the action when you save it.

After you add the schema, Sentry lists the integration as its own action, and no longer under Send a notification via an integration. Alerts that already use that action keep working. The integration's own action also sends issue and activity alerts, as issue_alert.triggered and activity_alert.triggered.

EventsCopy Anchor Link

All filters are optional. An empty filter matches every event.

• Project matches the project's slug. The list shows the organization's projects, up to 5,000. A metric alert that covers several projects matches when any of them is selected.
• Level is the issue's or event's level: fatal, error, warning, info, or debug.
• Environment matches the event's or the metric alert's environment, such as production or staging-*.
• Alert rule matches the Alert's name, such as Checkout *.
• Severity is the threshold a metric alert reached: critical or warning.
• Activity is the issue activity that fired an activity alert, such as Resolved, Regressed, Root cause analysis completed or Pull request created.

Environment and alert rule are patterns, and case matters. An event with no environment never matches an environment filter. Seer events name the issue only by its ID, so they have no filters.

When you save the connection, Helios checks which events can reach it. The trigger picker shows the others as unavailable, with the reason:

• installation.created and installation.deleted on Sentry Auth Token connections, because Sentry sends them only to public integrations.
• error.created when your Sentry plan doesn't include error webhooks.

Helios can't check whether the integration has the schema for metric alerts, so metric_alert.triggered and metric_alert.resolved are always available.

Deliveries are verified with the HMAC-SHA256 Sentry-Hook-Signature header, signed with the integration's client secret.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Sentry rejected the token or the organization slug.
• The webhook: in Sentry, open Settings → Developer Settings → Custom Integrations and click Dashboard next to the integration. The Request Log lists each delivery to Helios with its status code.
• A trigger:
  1. Add issue.created to a workflow with no filters.
  2. Send a new error to a Sentry project so that a new issue is created.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
• An alert: repeat the steps with issue_alert.triggered and an Alert that fires on new issues.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Sentry rate limits each API endpoint separately, per caller. Responses carry X-Sentry-Rate-Limit-* headers that show the limit and what's left. See Sentry's rate limits.