Last updated Dec 11, 2024

Create custom webhooks

Get data quickly and easily from across your toolchain into Compass with custom webhooks. Visualize component events from all your tools in a unified place in real time. Use those events to power metrics and scorecard calculations to get strong guidance toward cultivating and maintaining healthy DevOps practices.

Creating a custom webhook gives you a unique URL, which you can use to send events from your tools to one or more Compass components. With minor configurations in your tools and the provided payload transformations, you can get the data flowing into Compass.

Learn more about custom webhooks

Before you begin

Ensure you have the custom webhooks Forge app installed on your Compass instance.

Create a custom webhook

  1. In the main navigation, select the Apps dropdown.
  2. Select the Custom Webhooks for Compass extension point.
  3. Select Create.
  4. Fill out the webhook details:
    • Select event type
    • Input the mappings for event fields

Event payload transformation

Given the following GitHub deployment event payload:

1
2
{
   "action": "created",
   "repository": {
      "id": "01",
      "name": "myRepo",
      "html_url": "https://www.examplerepository.com",
      "default_branch": "main"
   },
   "deployment": {
      "id": "23",
      "description": "Push to prod",
      "environment": "production",
      "created_at": "2015-06-08T21:34:56+00:00",
      "updated_at": "2015-06-09T03:34:49+00:00",
      "url": "https://www.exampledeployment.com"
   },
   "deployment_status": {
      "state": "success"
   }
}

We can form the following mapping to the compass fields:

1
2
{
   "url": "deployment.url",
   "displayName": ".deployment.description",
   "description": ".deployment.description",
   "updateSequenceNumber": "113456",
   "lastUpdated": ".deployment.updated_at",
   "state": ".deployment_status.state",
   "deploymentSequenceNumber": ".deployment.id",
   "environment": {
      "displayName": ".deployment.environment",
      "id": ".deployment.environment",
      "type": ".deployment.environment"
   },
   "deploymentStartedAt": ".deployment.created_at",
   "deploymentCompletedAt": ".deployment.updated_at"
}

In the following example when mapping the GitHub push event to the Compass push event we would pass in reference to the parameters we intend to pass into each field. One example being the deployment event's URL values which is nested in the payload. When passing that value over to Compass we would refer to it by passing in deployment.url Using the data from the sample payload the resulting Compass deployment event would look like:

1
2
{
   "url": "https://www.exampledeployment.com",
   "displayName":"Push to prod",
   "description": "Push to prod",
   "updateSequenceNumber": "113456",
   "lastUpdated": "2015-06-08T21:34:56+00:00",
   "state": "success",
   "deploymentSequenceNumber": "23",
   "environment": {
      "displayName": "production",
      "id": "production",
      "type": "production"
   },
   "deploymentStartedAt": "2015-06-08T21:34:56+00:00",
   "deploymentCompletedAt": "2015-06-08T21:34:56+00:00"
}

Enum Mapping

The values for deployment state and environment for your deployment payload may not match the valid set Compass deployment event states. As such during custom webhooks creation you are expected to map the expected value of your payload to the matching Compass deployment event state. Here is an example of enum mappings:

1
2
{
   "enumsMap": {
      "deployment-states": {
         "not-finished": "CANCELLED",
         "fail": "FAILED",
         "working": "IN_PROGRESS",
         "undefined": "UNKNOWN",
         "no-op": "ROLLED_BACK",
         "success": "SUCCESSFUL"
      },
      "deployment-categories": {
         "dev": "DEVELOPMENT",
         "prod": "PRODUCTION",
         "stg": "STAGING",
         "undefined": "UNMAPPED"
      }
   }
}

In this instance if the payload has a state value of not-finished based on this mapping stored for the custom webhooks that resulting Compass deployment event would have a state of CANCELLED.

Component Id Mapping

In order to properly map the custom webhook events and metrics to proper components the payload need to have either property or mapping to uniquely identify components. During custom webhook creation you will be required to a field in your payload which contains the compass component ID, or a unique property to identify the component. If your payload has contains the component ID, this is all you need to do, and you don't need to specify a component ID mapping. If your payload does not contain the component ID, you can map values in your payload to their corresponding component IDs.

Given the following incoming payload where you have the component ID stored in a property, You would need to point to that payload field without having to provide any mapping depending on the value of said field:

1
2
{
   ...
   "deployment": {
      "id": "23",
      "description": "Push to prod",
      "environment": "production",
      "created_at": "2015-06-08T21:34:56+00:00",
      "updated_at": "2015-06-09T03:34:49+00:00",
      "url": "https://www.exampledeployment.com"
   },
   "compassMetadata": {
      "componentId": "ari:cloud:compass:0000002002020/component:02029929092"
   },
   ...
}

The resulting component ID mapping for this webhook would then look like:

1
2
{
   "componentIdsMap": {
      "componentMap": {},
      "payloadComponentField": ".compassMetadata.componentId"
   }
}

However, if you were to map specific deployment IDs to different components IDs, you would provide the relevant field as well as my different mappings for said field. as show below:

1
2
{
   "componentIdsMap": {
      "componentMap": {
         "23": "ari:cloud:compass:0000002002020/component:02029929092",
         "2": "ari:cloud:compass:0000002002020/component:02021112288"
      },
      "payloadComponentField": ".deployment.id"
   }
}

Rate this page: