Webhooks

Overview

Webhooks are how GitVelocity receives real-time events from your version control provider. When a pull request is opened, updated, or merged, GitHub (or Bitbucket/GitLab) sends an event to GitVelocity, which triggers scoring based on your score settings.

How Webhooks Work

During repository setup, GitVelocity registers a webhook with your VCS provider. From that point on, the provider sends event payloads to GitVelocity automatically whenever relevant PR activity occurs. No manual intervention is needed for normal operation.

Webhook Status

The Processing Log page (under Admin Tools in the settings sidebar) shows the delivery and processing status of every webhook event received from your VCS provider.

Processing Log page with title and a 'How Processing Works' info card explaining that every webhook event is logged here, filter tabs (All, Failed, Processed, Queued, Ignored), and a Recent Deliveries table header row showing Status, Repository, PR, Event, Received, Processed, Error, Actions columns Filter by tab to triage — Failed surfaces deliveries that errored, Queued shows backlog, Ignored explains why an event wasn't scored, and the Actions column lets you retry a failed delivery.

For each delivery you can see:

  • Status -- whether the job was processed, queued, ignored, or failed
  • Repository and PR -- which repository and pull request the event was for
  • Event type -- the GitHub event name (e.g. pull_request.opened, pull_request.synchronize)
  • Timestamps -- when the event was received and when processing completed
  • Error -- the error message for any failed deliveries, with a retry action

A healthy connection shows recent activity in the Processed tab and few or no entries in Failed. If a repository hasn't sent events in a while, that may indicate a problem.

Troubleshooting

If PRs aren't being scored, check the following:

No Events Received

  • Verify the webhook is still registered in your VCS provider's settings (GitHub: repository Settings > Webhooks)
  • Check that the repository is still connected in GitVelocity
  • Confirm that the VCS provider isn't experiencing an outage

Events Received but Not Scored

  • Check if scoring is paused for the repository
  • Verify the PR isn't being caught by an exclusion filter
  • Confirm the PR targets the default branch (PRs merged to non-default branches are not scored by default)

Delivery Failures

  • Temporary failures usually resolve on their own -- VCS providers retry failed deliveries
  • Persistent failures may indicate a permissions change on the repository
  • If the webhook secret has been rotated or the webhook was deleted and recreated, you may need to reconnect the repository in GitVelocity