Skip to content
Sourcegraph Help Center home
Sourcegraph Help Center home

Rotating the GitHub App Webhook Secret in Sourcegraph

Overview

Sourcegraph's GitHub App integration has three components, each with its own credentials:

  • Repository syncing — uses OAuth
  • User auth & permissions syncing — uses OAuth
  • Webhooks — uses a shared secret (token)

This article covers how to rotate the webhook secret specifically. Webhooks allow GitHub to push real-time events to Sourcegraph (e.g. permission changes, pull request status updates for Batch Changes). If the secret is compromised, out of sync, or you need to rotate it as part of a security policy, follow the steps below.

When to rotate the webhook secret

  • Routine secret rotation as part of your security policy
  • The shared secret was accidentally exposed
  • Webhook events are no longer being received by Sourcegraph (mismatch between GitHub and Sourcegraph)

Step 1 — Generate a new secret

Generate a strong, random string to use as the new secret. You can use the following command:

LC_ALL=C tr -dc 'A-Za-z0-9!"#$%&()*+,-./:;<=>?@[\]^_{|}~' < /dev/urandom | head -c 100; echo

Copy the output — you will need it in both places below.

Step 2 — Update the secret on GitHub

  1. Go to your GitHub organization's settings page (e.g. https://github.com/organizations/<your-org>/settings/apps).
  2. Click on the Sourcegraph GitHub App.
  3. Scroll to the Webhook section.
  4. Replace the existing value in the Webhook secret field with your new secret.
  5. Click Save changes.

Step 3 — Update the secret in Sourcegraph

  1. Log in to your Sourcegraph instance as a site admin.
  2. Navigate to Site admin → Incoming webhooks (not the Code host connections page).
  3. Find the GitHub webhook entry and click to edit it.
  4. Replace the secret field with the same value you set in GitHub.
  5. Save the changes.

Step 4 — Verify webhook delivery

  1. In Sourcegraph, stay on the Incoming webhooks page and check that new events are appearing after saving.
  2. In GitHub, go to your App settings → Advanced → Recent Deliveries and confirm recent deliveries show a 200 status code.

Troubleshooting webhook delivery failures

HTTP 444 or other non-2xx status codes from GitHub

A 444 response (or similar connection-refused/dropped errors) typically indicates a network or firewall issue — not a secret mismatch. This happens when GitHub cannot reach your self-hosted Sourcegraph instance over HTTPS.

Resolution: Ensure your firewall has an allow rule for inbound HTTPS traffic (TCP 443) from GitHub's IP ranges to your Sourcegraph instance. You can find GitHub's current IP ranges at https://api.github.com/meta (look for the hooks key).

Webhooks not delivering but repos are still syncing

If your repositories are receiving updates even though webhooks are failing, Sourcegraph is likely falling back to polling your code host. Polling is a background mechanism that periodically fetches the latest state from GitHub, but it is less timely than webhooks and does not cover all event types (e.g. permission syncing, Batch Changes PR status). Fixing webhook delivery is recommended.

Secret mismatch (webhooks deliver but events are rejected)

If GitHub shows successful deliveries (2xx) but Sourcegraph is not processing them, the secrets may be out of sync. Repeat Steps 1–3 above to reset both sides to the same value.

Related resources

Powered by Plain