Webhooks

To optionally enable webhooks to trigger the scanner automatically, make sure the scanner is run on cron as normal, but at a higher frequency (perhaps once every 2 minutes) and then set the PULL_THRESHOLD in settings.py to something like 120 minutes. This means that without a webhook, a repository will only be pulled very sporadically, but there is still a safeguard in case IT or GitHub breaks the routing of your webhooks.

Configuring SourceOptics and Your Git Provider

In Django admin, on each organization, set the webhooks_enabled boolean to True.

The SourceOptics URL to configure in GitHub or Jenkins is of the form "http://yourserver:yourport/webhook". The webhook must be set to send JSON.

Webhook Security

On each repository, an optional webhook security token is available to prevent abuse of a webhook. If a token is set to 'acme1234', configure the webhook as "http://yourserver/webhook?token=1234" If the token is not set on a repository, the value can be taken from the organization. You should pick a much longer string than 'acme1234'!

Note that webhooks have only been tested with GitHub and involve matching on the URLs on the repositories. Improvements, particularly to support other hosting providers is a welcome addition.

How Things Work

When a commit happens, the external system will send a JSON POST to SourceOptics, and SourceOptics will flag the repository to be scanned in the very next scanner pass. Be sure that the scanner is configured to run on a tight enough cron loop, as described above.