> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Sentry

Sentry iconSentry icon
Loading version...

Port's Sentry integration allows you to model Sentry resources in your software catalog and ingest data into them.

Supported resources External link iconUserTeamProjectProject TagIssueIssue Tag

Core support

Live eventsSee supported resources

Prerequisites​

  • A Sentry account with access to the organization you want to sync.

  • Your Port user role is set to Admin.

  • A Sentry API token for resyncing data into Port.

    Required permissions (click to expand)
    • Issue & Event: Read (event:read) - for syncing issues and issue tags.
    • Member: Read (member:read) - for syncing organization members and teams.
    • Organization: Read (org:read) - for organization-level API access.
    • Project: Read (project:read) - for syncing projects and project tags.
    • Team: Read (team:read) - for syncing teams and team members.

Setup​

Choose one of the following installation methods: Not sure which method is right for your use case? Check the available installation methods.

Choose method

Configuration​

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
- kind: user
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .email
        title: .user.name
        blueprint: '"sentryUser"'
        properties:
          username: .user.username
          isActive: .user.isActive
          dateJoined: .user.dateJoined
          lastLogin: .user.lastLogin
          orgRole: .orgRole
          inviteStatus: .inviteStatus
- kind: user
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .email
        blueprint: '"_user"'
        relations:
          sentry_user: .email
- kind: project-tag
  selector:
    query: 'true'
    tag: environment
  port:
    entity:
      mappings:
        identifier: .slug + "-" + .__tags.name
        title: .name + "-" + .__tags.name
        blueprint: '"sentryProjectEnvironment"'
        properties:
          dateCreated: .dateCreated
          platform: .platform
          status: .status
          link: .organization.links.organizationUrl + "/projects/" + .name
- kind: issue-tag
  selector:
    query: 'true'
    tag: environment
  port:
    entity:
      mappings:
        identifier: .id + "-" + .item.name
        title: .title + " -" + " " + .item.name
        blueprint: '"sentryIssue"'
        properties:
          link: .permalink + "?environment=" + .item.name
          status: .status
          isUnhandled: .isUnhandled
        relations:
          projectEnvironment: (.project.slug as $slug | .item | "\($slug)-\(.name)")
          assignee:
            combinator: '"and"'
            rules:
            - operator: '"="'
              property: '"$identifier"'
              value: .assignedTo.email
- kind: team
  selector:
    query: 'true'
    includeMembers: true
  port:
    entity:
      mappings:
        identifier: .slug
        title: .name
        blueprint: '"sentryTeam"'
        properties:
          dateCreated: .dateCreated
          memberCount: .memberCount
          roles: .teamRole
          projects: .projects | map (.slug)
        relations:
          members: if .__members != null then .__members | map(.user.email) | map(select(. != null)) else [] end

Mapping & selectors per resource​

Examples of blueprints and the relevant integration configurations:

Set up live events​

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

Live events base URL

For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.

Call the endpoint with your integration's identifier:

curl -X GET \
  'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
  -H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

In the response, look for the following fields under spec.appSpec:

{
  "spec": {
    "appSpec": {
      "liveEventsUuid": "abcdefghijk",
      "liveEventsIngestHostname": "ingest.ocean.getport.io"
    }
  }
}

Combine them to build the live events base URL:

https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>

For example, with the values above, the live events base URL is:

https://ingest.ocean.getport.io/live-events/abcdefghijk

This is the same URL configured for the integration.

To update Port in real time when Sentry issues change, create an internal integration in Sentry and configure it to send issue webhooks to Port.

Get the webhook URL​

First create a custom webhook integration in Port, then connect it to Sentry in Create the internal integration in Sentry:

  1. Go to the connectors page in Port.
  2. Select the Webhook tab.
  3. Click Custom integration. For more details, see the custom webhook integration guide.
  4. Enter a name for the integration (e.g Sentry Webhook).
  5. Enter a description for the integration.
  6. Click Next.
  7. After the custom integration is created, open its card.
  8. Select the Mapping tab.
  9. In the Configure Webhook event section, copy the webhook URL. You'll paste it in the Sentry internal integration steps below.
  10. In the Map the data from the external system into Port section, add a mapping for Sentry issue events. The mapping uses JQ to select and transform fields from the webhook payload.
Test your mapping

Use the Test mapping section to verify that the JQ mapping works with a Sentry webhook payload before saving.

Example mapping (click to expand)
[
  {
    "blueprint": "sentryIssue",
    "operation": "create",
    "filter": ".body.data.issue.id != null",
    "entity": {
      "identifier": ".body.data.issue.id",
      "title": ".body.data.issue.title",
      "properties": {
        "link": ".body.data.issue.permalink",
        "status": ".body.data.issue.status",
        "isUnhandled": ".body.data.issue.isUnhandled"
      },
      "relations": {
        "projectEnvironment": ".body.data.issue.project.slug"
      }
    }
  }
]
Example webhook payload (click to expand)
{
  "body": {
    "action": "resolved",
    "data": {
      "issue": {
        "id": "7324623130",
        "shortId": "PROJECT-8V",
        "title": "N+1 Query",
        "permalink": "https://example.sentry.io/issues/7324623130/",
        "level": "info",
        "status": "resolved",
        "isUnhandled": false,
        "project": {
          "id": "4509038422523904",
          "name": "example-api",
          "slug": "example-api",
          "platform": "python-django"
        },
        "firstSeen": "2026-03-10T14:44:04.743762Z",
        "lastSeen": "2026-06-09T11:20:54.358658Z"
      }
    },
    "actor": {
      "type": "user",
      "name": "Example User"
    }
  },
  "headers": {
    "Sentry-Hook-Resource": "issue",
    "Sentry-Hook-Signature": "<signature>",
    "Sentry-Hook-Timestamp": "1781025505"
  },
  "queryParams": {}
}

Create the internal integration in Sentry​

  1. Log in to Sentry with your organization's credentials.
  2. Click the gear icon (Setting) at the left sidebar of the page.
  3. Under Integrations, click Custom Integrations.
  4. At the upper corner of this page, click on Create New Integration.
  5. Sentry provides two types of integrations: Internal and Public. For the purpose of this guide, choose Internal Integration and click on the Next button.
  6. Under Internal Integration Details, input the following details:
    • Name - use a meaningful name such as "Port Webhook".
    • Webhook URL - paste the URL from the webhook URL instructions for your installation method.
  7. Under Permissions, grant Read permissions for the Issue & Event category.
  8. Under Webhooks, enable the issues checkbox to allow Sentry to report issue events to Port.
  9. Click Save Changes at the bottom of the page.
Save the client secret

After saving the internal integration, Sentry displays a client secret. Copy it if you want Port to verify the signature of webhook requests from Sentry.

For more details on setting up internal integrations in Sentry, see the Sentry documentation.

Verify webhook signatures​

Signature verification is optional. To enable it, use the client secret generated by Sentry when you created the internal integration.

  1. Select the custom webhook integration's Settings tab.
  2. Paste the client secret from Sentry's internal integration in the Secret field.
  3. Set Signature Header Name to Sentry-Hook-Signature.
  4. Set Signature Algorithm to sha256.
  5. Click Save.

Webhook signature settings

Monitoring and sync status​

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.