Configure incoming webhooks

Get data quickly and easily from across your toolchain into Compass with incoming 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 an incoming 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 linking your Compass components to those tools, you can get the data flowing into Compass. Learn more about incoming webhooks

The configuration steps may vary for different tools. Go to the specific section on this page for the tool you're configuring for incoming webhooks.

After you configure the incoming webhook:

• Events begin to appear on the component's activity feed as they occur.
• Compass automatically calculates associated derived metrics upon receiving the first event and shows the metric card on the component's overview page. The metric values are recalculated when subsequent events occur over time.
• If any derived metrics are added as scorecard criteria, the scores are updated each time the metric values are recalculated, thus updating the component's score each time.

Before you begin

• Ensure you have a full user role in Compass.

• You'll need a unique webhook URL to configure into your source tool. You can either create a new incoming webhook or use an existing incoming webhook.

Configure incoming GitHub and GitHub Enterprise Server webhooks

Compass can get the following events from GitHub (includes GitHub Free, Team, Pro, and Enterprise Cloud) and GitHub Enterprise Server using incoming webhooks:

• Deployment
• Build
• Push

You can create repository webhooks (as a repository owner or with admin access) and organization webhooks (as an organization owner) on both GitHub and GitHub Enterprise Server.

• Repository webhooks can send events only from those repositories to their corresponding Compass components.

• Organization webhooks can send events from all repositories within the organization to their corresponding Compass components.

Get the webhook URL from Compass

1. When creating a new incoming webhook, while on the Configure webhook screen, select Copy webhook URL ().

2. When reusing an existing incoming GitHub or GitHub Enterprise Server webhook, go to the Incoming webhooks page, find the webhook you want, and select Copy webhook URL () next to it.

Add a webhook in GitHub or GitHub Enterprise Server

1. Go to GitHub or your GitHub Enterprise Server instance.

2. Go to Settings > Webhooks in individual repositories or your organization

3. Add a new webhook.

4. In the Payload URL field, add the webhook URL you copied in Compass earlier.

5. From the Content type menu, select application/json.

6. Under Which events would you like to trigger this webhook?, select Let me select individual events. Then, select one or more supported events:

   • Deployment statuses (for deployment events)
   • Pushes (for push events)
   • Workflow runs (for build events)

7. Add the webhook.

For more details, refer to appropriate GitHub documentation version:

• Creating webhooks - GitHub Docs
• Creating webhooks - GitHub Enterprise Cloud Docs
• Creating webhooks - GitHub Enterprise Server 3.11 Docs (you may have to switch to the documentation version as per your GitHub Enterprise Server version)

Add repository URLs to Compass components

1. Copy and add the GitHub repository link to the Repositories section on the component's Overview page in Compass.

2. Repeat for all repositories that you need to link to components.

Configure incoming Bitbucket Cloud webhooks

Compass can get the following events from Bitbucket Cloud using incoming webhooks:

• Push
• Build

You can create webhooks on Bitbucket Cloud repositories (requires administrator access) to send events from those repositories to their corresponding Compass components.

Get the webhook URL from Compass

1. When creating a new incoming webhook, while on the Configure webhook screen, select Copy webhook URL ().

2. When reusing an existing incoming BitBucket Cloud webhook, go to the Incoming webhooks page, find the webhook you want, and select Copy webhook URL () next to it.

Add a webhook to Bitbucket

1. Go to your Bitbucket Cloud repository.

2. Select Repository Settings > Webhooks from the left sidebar

3. Add a new webhook.

4. Give it a Title.

5. In the URL field, add the webhook URL you copied in Compass earlier.

6. Under Triggers, select one or more supported events:

   • Push (for push events)
   • Build status created (for build events)
   • Build status updated (for build events)

7. Choose any other configuration you need and select Save.

For more details, refer to Manage webhooks in the Bitbucket Cloud documentation.

Add repository URLs to Compass components

1. Copy and add the Bitbucket repository link to the Repositories section on the component's Overview page in Compass.

2. Repeat for all repositories that you need to link to components.

Configure incoming GitLab and GitLab self-managed webhooks

Compass can get the following events from GitLab (includes GitLab SaaS and GitLab Dedicated) and GitLab self-managed instances using incoming webhooks:

• Deployment

• Build

• Push

You can create webhooks in groups or individual projects on both GitLab and GitLab self-managed instances.

• A group webhook can send events from all subgroups and projects within the group to their corresponding Compass components

• A project webhook can send events only from that project to their corresponding Compass component

Copy the webhook URL from Compass

• When creating a new incoming webhook, while on the Configure webhook screen, select Copy webhook URL ().

• When reusing an existing incoming GitLab or GitLab self-managed webhook, go to the Incoming webhooks page, find the webhook you want, and select Copy webhook URL () next to it.

Add a webhook to GitLab

1. Go to your project or group in GitLab or your GitLab self-managed instance.

2. Select Settings > Webhooks from the left sidebar.

3. Add a new webhook.

4. Add the webhook URL you copied in Compass earlier in the URL field.

5. Under Trigger, select one or more supported events:

   • Deployment event

   • Push event

     • This event sends push events from all branches of the project to Compass by default. We recommend you choose to send events only from the default branch and other select branches by using wildcards or regular expressions unless you want to send events from all branches.

   • Pipeline event (for build events)

6. Add the webhook.

For the detailed procedure, refer to Webhooks in GitLab documentation.

Add project URLs to Compass components

1. Copy and add the GitLab project link to the Repositories section on the component's Overview page in Compass.

2. Repeat for all projects that you need to link to components.

Next steps

• View a component's activity feed to see the events
• View component' details to see derived metrics and scorecards that may have been updated.

Troubleshooting

I've added a webhook in GitHub or GitHub Enterprise Server, but I still can't see events in Compass

There are a few things you can check:

• Check that you've linked the GitHub repository to the Compass component. This step is required for events to appear on the component’s activity feed in Compass.

• Check that you selected the correct event types in GitHub — Deployment statuses (for deployment events, Pushes (for push events), and Workflow runs (for build events)in GitHub.

• Check that an event has occurred at source.

  • Go to GitHub or your GitHub Enterpriser server instance.
  • Go to Settings > Webhooks for either individual repositories or your organization.
  • Select the webhook URL for which you'd like to see deliveries.
  • Select Recent Deliveries to see if an event occurred. You won’t see it in Compass if there is no event in GitHub.

  For more details, refer to appropriate GitHub documentation version:

  • Viewing webhook deliveries - GitHub Docs
  • Viewing webhook deliveries - GitHub Enterprise Cloud Docs
  • Viewing webhook deliveries - GitHub Enterprise Server 3.11 Docs (you may have to switch to the documentation version as per your GitHub Enterprise Server version)

• Check that your GitHub Enterprise Server instance is on version 3.11 or higher.

I've added a webhook in Bitbucket, but I still can't see events in Compass

There are a few things you can check:

• Check that you've linked the correct Bitbucket Cloud repository to the Compass component. This step is required for events to appear on the component's activity feed in Compass.

• Check that you selected the supported event types for your source tool – Push (for push events), Build status created (for build events), and Build status updated (for build events)

• Check that an event has occurred at the source.

  • Go to the Webhooks page in Bitbucket.
  • Look for your webhook under the Repository hooks section
  • Select View requests to see the events the webhook sent.

I've added a webhook in GitLab or GitLab self-managed instance, but I still can't see events in Compass

There are a few things you can check:

• Check that you've linked the correct GitLab project to the Compass component. This step is required for events to appear on the component's activity feed in Compass.

• Check that you selected the supported event types for your source tool – Deployment event, Push event, and Pipeline event (for build events).

• Review the webhook history and the recent events table to check that events have occurred. For more details, refer to Troubleshooting In GitLab documentation.

• Check that your GitLab self-managed instance is on version 16.8 or higher.

I can't see any derived metrics on the component

Derived metrics are calculated only when the first event is sent to Compass. A metric card is then added to the component.

I can see a derived metric's source as an app instead of an incoming webhook

Check if an app for the same tool as your incoming webhook is configured for your site. If so, Compass only receives events from the app to prevent duplication. Compass resumes receiving events from the incoming webhook when the app is uninstalled.