Sentry

In this example you are going to create a webhook integration between Sentry and Port, which will ingest issues entities.

Prerequisites

Create the following blueprint definitions and webhook configuration:

Sentry issue blueprint

{
  "identifier": "sentryIssue",
  "description": "This blueprint represents an issue trigger event from Sentry",
  "title": "Sentry Issue Event",
  "icon": "Sentry",
  "schema": {
    "properties": {
      "level": {
        "type": "string",
        "title": "Level",
        "enum": ["error", "info", "fatal", "warning", "debug", "sample"]
      },
      "platform": {
        "type": "string",
        "title": "Platform",
        "description": "the platform name in Sentry"
      },
      "status": {
        "type": "string",
        "title": "Issue Status"
      },
      "projectID": {
        "type": "string",
        "title": "Project ID",
        "description": "the ID of the project in Sentry"
      },
      "action": {
        "type": "string",
        "title": "Action",
        "enum": ["created", "resolved", "assigned", "ignored"]
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}

Sentry issue webhook configuration

{
  "identifier": "sentryIssuesMapper",
  "title": "Sentry mapper",
  "description": "A webhook configuration to map Sentry Issues to Port",
  "icon": "Sentry",
  "mappings": [
    {
      "blueprint": "sentryIssue",
      "entity": {
        "identifier": ".body.data.issue.id",
        "title": ".body.data.issue.title",
        "properties": {
          "action": ".body.action",
          "level": ".body.data.issue.level",
          "platform": ".body.data.issue.platform",
          "status": ".body.data.issue.status",
          "projectID": ".body.data.issue.project.id"
        }
      }
    }
  ],
  "enabled": true,
  "security": {
    "signatureHeaderName": "sentry-hook-signature",
    "signatureAlgorithm": "sha256"
  }
}

tip

We have left out the secret field from the security object in the webhook configuration because the secret value is generated by Sentry when creating the webhook. So when following this example, please first create the webhook configuration in Port. Use the webhook URL from the response and create the webhook in Sentry. After getting the secret from Sentry, you can go back to Port and update the webhook configuration with the secret.

Create the Sentry webhook

1. Log in to Sentry with your organization's credentials;
2. Click the gear icon (Setting) at the left sidebar of the page;
3. Choose Developer Settings;
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. Input the following details:
   1. Name - use a meaningful name such as Port Webhook;
   2. Webhook URL - enter the value of the url key you received after creating the webhook configuration;
   3. Overview - enter a description for the webhook;
   4. Permissions - Grant your webhook Read permissions for the Issue & Event category;
   5. Webhooks - Under this section, enable the issues checkbox to allow Sentry to report issue events to Port;
7. Click Save Changes at the bottom of the page.

tip

Now that the webhook is created, you can take the secret value generated by Sentry and use it to update the security object in your Port webhook configuration

Relate comments to Issues

The following example adds a sentryComment blueprint, in addition to the sentryIssue blueprint shown in the previous example. In addition, it also adds a sentryIssue relation. The webhook will create or update the relation between the 2 existing entities, allowing you to map which issue a comment is made on:

Sentry comments blueprint (including the sentryIssue relation)

{
  "identifier": "sentryComment",
  "description": "This blueprint represents a Sentry comment in our software catalog",
  "title": "Sentry Comment",
  "icon": "Sentry",
  "schema": {
    "properties": {
      "action": {
        "type": "string",
        "title": "action",
        "enum": ["created", "updated", "deleted"]
      },
      "comment": {
        "type": "string",
        "title": "Comment"
      },
      "project": {
        "type": "string",
        "title": "Project Slug"
      },
      "issue_id": {
        "type": "string",
        "title": "Issue ID"
      },
      "timestamp": {
        "type": "string",
        "title": "Comment Timestamp"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "sentryIssue": {
      "title": "Issue",
      "target": "sentryIssue",
      "required": false,
      "many": false
    }
  }
}

Sentry comments webhook configuration

{
  "identifier": "sentryMapper",
  "title": "Sentry mapper",
  "description": "A webhook configuration to map Sentry Comments to Port",
  "icon": "Sentry",
  "mappings": [
    {
      "blueprint": "sentryComment",
      "entity": {
        "identifier": ".body.data.comment_id",
        "title": "Comment Event",
        "properties": {
          "action": ".body.action",
          "comment": ".body.data.comment",
          "project": ".body.data.project_slug",
          "issue_id": ".body.data.issue_id",
          "timestamp": ".body.data.timestamp"
        },
        "relations": {
          "sentryIssue": ".body.data.issue_id | tostring"
        }
      }
    }
  ],
  "enabled": true,
  "security": {
    "signatureHeaderName": "sentry-hook-signature",
    "signatureAlgorithm": "sha256"
  }
}

tip

In order to view the different payloads and events available in Sentry webhooks, look here

Done! any issue and comment in Sentry will trigger a webhook event. Port will parse the events according to the mapping and update the catalog entities accordingly.