Skip to Content
FeaturesWebhooks

Webhooks

Webhooks connect your SCM provider (GitHub or Bitbucket) to CodeStax, enabling automatic security reviews when code changes happen.

Supported Events

GitHub

EventTriggerCodeStax Action
pull_request.openedA new PR is createdTriggers PR review
pull_request.synchronizeNew commits pushed to a PRRe-triggers PR review
pull_request.reopenedA closed PR is reopenedTriggers PR review
pushCode pushed to a branchTriggers auto-scan (if enabled in policy)

Bitbucket

EventTriggerCodeStax Action
pullrequest:createdA new PR is createdTriggers PR review
pullrequest:updatedPR is updated with new commitsRe-triggers PR review
repo:pushCode pushed to a branchTriggers auto-scan (if enabled in policy)

Setup

If you connected your repository via OAuth, CodeStax can configure webhooks automatically:

  1. Go to Repository Settings → Webhooks
  2. Click Enable Auto-Review
  3. CodeStax registers the webhook with your SCM provider
  4. Verify the status shows “Active”

Manual Setup — GitHub

  1. Go to your GitHub repository → Settings → Webhooks → Add webhook
  2. Configure:
    • Payload URL: https://codestax.co/api/v1/webhooks/github
    • Content type: application/json
    • Secret: Copy from Repository Settings → Webhooks → Webhook Secret in CodeStax
    • Events: Select “Pull requests” and optionally “Pushes”
  3. Click Add webhook
  4. Verify delivery with a test ping

Manual Setup — Bitbucket

  1. Go to your Bitbucket repository → Settings → Webhooks → Add webhook
  2. Configure:
    • Title: CodeStax Security
    • URL: https://codestax.co/api/v1/webhooks/bitbucket
    • Triggers: Select “Pull Request: Created”, “Pull Request: Updated”, and optionally “Repository: Push”
  3. Click Save
  4. Verify with a test event

Webhook Security

Signature Verification

All incoming webhooks are verified using HMAC signatures:

  • GitHub: X-Hub-Signature-256 header validated against your webhook secret
  • Bitbucket: Request origin verified against Bitbucket IP ranges

Invalid signatures are rejected with a 401 Unauthorized response.

Webhook Status

View webhook status in Repository Settings → Webhooks:

StatusMeaning
ActiveWebhook is registered and receiving events
InactiveWebhook is registered but disabled
ErrorLast delivery failed — check the error message
Not configuredNo webhook registered for this repository

Event Processing

When a webhook event is received:

  1. Signature validation — reject if invalid
  2. Event filtering — only process supported event types
  3. Repository lookup — match to a connected repository
  4. Policy check — verify the event matches the repo’s policy (e.g., scan_on_pr is enabled)
  5. Deduplication — skip if the same commit is already being reviewed
  6. Trigger — queue the PR review or scan

Processing typically takes 1-3 seconds before the scan or review begins.

Troubleshooting

IssueSolution
Webhook shows “Error”Check the delivery log in your SCM provider for the HTTP response
PR reviews not triggeringVerify the webhook secret matches between SCM and CodeStax
Duplicate reviewsEnsure only one webhook is registered (not both auto and manual)
Events delayedCheck CodeStax status page; processing may be queued during high load
401 Unauthorized responseWebhook secret mismatch — regenerate in CodeStax and update in SCM

Disabling Webhooks

To stop automatic reviews:

  1. Go to Repository Settings → Webhooks
  2. Click Disable Auto-Review
  3. The webhook is deactivated but not deleted — you can re-enable it later

To permanently remove, also delete the webhook from your SCM provider’s settings.

Compliance ReportsAuto-Scan on Push