Incoming webhooks

Incoming webhooks can be configured on a Sourcegraph instance in order to receive webhook events from code hosts. This allows Sourcegraph to react more quickly to events that occur outside the instance instead of polling for changes.

Webhooks are currently implemented to speed up two types of external events:

  • Keeping batch changes changeset details up to date
  • Keeping code on Sourcegraph fresh by responding to new code being pushed to a repository

See the table below for code host compatibility:

Code host Batch changes Code push User permissions
GitHub 🟢 🟢 🟢
GitLab 🟢 🟢 🔴
Bitbucket Server / Datacenter 🟢 🟢 🔴
Bitbucket Cloud 🟢 🟢 🔴

To receive webhooks both Sourcegraph and the code host need to be configured. To configure Sourcegraph, add an incoming webhook. Then configure webhooks on your code host

Adding an incoming webhook

Before adding an incoming webhook you should ensure that you have at least one code host connection configured.

The incoming webhook will be configured to accept events from a specific code host connection based on its type and URN.

  1. Navigate to Site Admin > Incoming webhooks Incoming webhooks page
  2. Click Add webhook Adding an incoming webhook
  3. Fill out the form:
    1. Webhook name: Descriptive name for the webhook.
    2. Code host type: Select from the dropdown. This will be filtered based on code host connections added on your instance.
    3. Code host URN: The URN for the code host. Again, this will be filtered by code host connections added on your instance.
    4. Secret: An arbitrary shared secret between Sourcegraph and the code host. A default value is provided, but you are free to change it.
  4. Click Create

The incoming webhook will now be created, and you will be redirected to a page showing more details. Created webhook

Use the unique URL present on the details page to configure the webhook on your code host.

Configuring webhooks on the code host

The instructions for setting up webhooks on the code host are specific to each code host type.

GitHub

Batch changes

  1. Copy the webhook URL displayed after adding the incoming webhook as mentioned above
  2. On GitHub, go to the settings page of your organization. From there, click Settings, then Webhooks, then Add webhook.
  3. Fill in the webhook form:
    • Payload URL: the URL you copied above from Sourcegraph.
    • Content type: this must be set to application/json.
    • Secret: the secret token you configured Sourcegraph to use above.
    • Which events: select Let me select individual events, and then enable:
      • Issue comments
      • Pull requests
      • Pull request reviews
      • Pull request review comments
      • Check runs
      • Check suites
      • Statuses
    • Active: ensure this is enabled.
  4. Click Add webhook.
  5. Confirm that the new webhook is listed.

Done! Sourcegraph will now receive webhook events from GitHub and use them to sync pull request events, used by batch changes, faster and more efficiently.

Code push

Follow the same steps as above, but ensure you include the push event under Let me select individual events

User permissions

Follow the same steps as above, but ensure you include the following events under Let me select individual events:

  • Collaborator add, remove, or changed
  • Memberships
  • Organizations
  • Repositories
  • Teams

When one of these events occur, a permissions sync will trigger for the relevant user or repository.

GitLab

Batch changes

  1. Copy the webhook URL displayed after adding the incoming webhook as mentioned above
  2. On GitLab, go to your project, and then Settings > Webhooks (or Settings > Integration on older GitLab versions that don't have the Webhooks option).
  3. Fill in the webhook form:
    • URL: the URL you copied above from Sourcegraph.
    • Secret token: the secret token you configured Sourcegraph to use above.
    • Trigger: select Merge request events and Pipeline events.
    • Enable SSL verification: ensure this is enabled if you have configured SSL with a valid certificate in your Sourcegraph instance.
  4. Click Add webhook.
  5. Confirm that the new webhook is listed below Project Hooks.

Done! Sourcegraph will now receive webhook events from GitLab and use them to sync merge request events, used by batch changes, faster and more efficiently.

NOTE: We currently do not support system webhooks as these provide a different set of payloads.

Code push

Follow the same steps as above, but ensure you include the Push events trigger.

Bitbucket server

Batch changes

The Sourcegraph Bitbucket Server plugin enables the Bitbucket Server / Bitbucket Data Center instance to send webhooks to Sourcegraph.

  1. Install the Sourcegraph Bitbucket Server plugin on your Bitbucket Server / Bitbucket Data Center instance.
  2. On your Bitbucket Server / Bitbucket Data Center instance, go to Administration > Add-ons > Sourcegraph
  3. Fill in the Add a webhook form
    • Name: A unique name representing your Sourcegraph instance.
    • Scope: global.
    • Endpoint: The URL found after creating an incoming webhook.
    • Events: repo:build_status, pr:activity:status, pr:activity:event, pr:activity:rescope, pr:activity:merge, pr:activity:comment, pr:activity:reviewers, pr:participant:status
    • Secret: The secret you configured when creating the incoming webhook.
  4. Confirm that the new webhook is listed under All webhooks with a timestamp in the Last successful column.

Done! Sourcegraph will now receive webhook events from Bitbucket Server / Bitbucket Data Center and use them to sync pull request events, used by batch changes, faster and more efficiently.

Code push

Follow the same steps as above, but ensure you tick the Push option. If asked for a specific event, use repo:refs_changed.

Bitbucket cloud

Batch changes

  1. On Bitbucket Cloud, go to each repository, and then Repository settings > Webhooks.
  2. Click Add webhook.
  3. Fill in the webhook form:
    • Title: Any title.
    • URL: The URL found after creating an incoming webhook.
    • Triggers: Select Build status created and Build status updated under Repository, and every item under Pull request.
  4. Click Save.
  5. Confirm that the new webhook is listed below Repository hooks.

Done! Sourcegraph will now receive webhook events from Bitbucket Cloud and use them to sync pull request events, used by batch changes, faster and more efficiently.

Code push

Follow the same steps as above, but ensure you tick the Push option.

Webhook logging

Sourcegraph can track incoming webhooks from code hosts to more easily debug issues with webhook delivery. These webhooks can be viewed in two places depending on how they were added:

  1. Via Site Admin > [Repositories] > Incoming webhooks Webhook logs
  2. Deprecated Via code host connection: Site Admin > [Batch Changes] > Incoming webhooks Legacy webhook logs

By default, sites without database encryption enabled will retain three days of webhook logs. Sites with encryption will not retain webhook logs by default, as webhooks may include sensitive information; these sites can enable webhook logging and optionally configure encryption for them by using the settings below.

Enabling webhook logging

Webhook logging is controlled by the webhook.logging site configuration option. This option is an object with the following keys:

Key Type Default Description
enabled boolean If true, incoming webhooks will be stored. true if no site encryption is enabled; false otherwise.
retention string The length of time to retain the webhooks, expressed as a valid Go duration. 72h

Examples

To disable webhook logging:

{
  "webhook.logging": {"enabled": false}
}

To retain webhook logs for one day:

{
  "webhook.logging": {
    "enabled": false,
    "retention": "24h"
  }
}

Encrypting webhook logs

Webhook logs can be encrypted by specifying a webhookLogKey in the on-disk database encryption site configuration.

Deprecation notice

As of Sourcegraph 4.3.0 webhooks added via code host configuration are deprecated and support will be removed in release 4.6.0.

This includes any webhooks pointed at URLs starting with the following:

  • .api/github-webhooks
  • .api/gitlab-webhooks
  • .api/bitbucket-server-webhooks
  • .api/bitbucket-cloud-webhooks

In order to continue using webhooks you need to follow the steps below to add an incoming webhook and then update the webhook configured on your code host with the new webhook url which will look something like https://sourcegraph-instance/.api/webhooks/{UUID}