Last updated Feb 29, 2024

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.

If an app and an incoming webhook for the same tool are configured for your site, Compass only receives events from the app to prevent duplication. Compass resumes receiving events using the incoming webhook when the app is uninstalled or unconfigured.

Before you begin

Treat the unique webhook URL like a secret. Be careful who you share it with, and store it like a password.

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.

Compass supports GitHub Enterprise Server version 3.11 or higher for use with incoming webhooks.

Get the webhook URL from Compass

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

  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 (Copy to clipboard icon) 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:

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.

You'll get events in Compass only when you link repositories to corresponding 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.

You can get deployment events from BitBucket repositories by integrating Compass with Bitbucket Cloud, and then adding repository links to Compass components. Learn how to set up Bitbucket Cloud as an event source

Get the webhook URL from Compass

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

  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 (Copy to clipboard icon) 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.

You'll get events in Compass only when you link repositories to corresponding 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

Compass supports GitLab self-managed version 16.8 or higher for use with incoming webhooks.

Copy the webhook URL from Compass

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

  • 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 (Copy to clipboard icon) 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.

You'll get events in Compass only when you link GitLab projects to corresponding components.

Next steps

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:

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:

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.

Rate this page: