compliance-scanner-agent/docs/guide/webhooks.md

Webhooks & PR Reviews

Webhooks let Certifai respond to events in your Git repositories automatically. When configured, pushes to your repository trigger scans, and pull requests receive automated security reviews.

What Webhooks Enable

• Automatic scans on push -- every time code is pushed to your default branch, a scan is triggered automatically
• PR security reviews -- when a pull request is opened or updated, Certifai scans the changes and posts a review comment summarizing any security findings in the diff

Finding the Webhook URL and Secret

Each repository in Certifai has its own webhook URL and secret:

1. Go to Repositories
2. Click Edit on the repository you want to configure
3. In the edit modal, you will find the Webhook URL and Webhook Secret
4. Copy both values -- you will need them when configuring your Git hosting provider

Setting Up Webhooks

Gitea

1. Go to your repository in Gitea
2. Navigate to Settings > Webhooks > Add Webhook > Gitea
3. Set the Target URL to the webhook URL from Certifai
4. Set the Secret to the webhook secret from Certifai
5. Under Trigger On, select:
   • Push Events -- for automatic scans on push
   • Pull Request Events -- for PR security reviews
6. Set the content type to application/json
7. Click Add Webhook

GitHub

1. Go to your repository on GitHub
2. Navigate to Settings > Webhooks > Add webhook
3. Set the Payload URL to the webhook URL from Certifai
4. Set the Content type to application/json
5. Set the Secret to the webhook secret from Certifai
6. Under Which events would you like to trigger this webhook?, select Let me select individual events, then check:
   • Pushes -- for automatic scans on push
   • Pull requests -- for PR security reviews
7. Click Add webhook

GitLab

1. Go to your project in GitLab
2. Navigate to Settings > Webhooks
3. Set the URL to the webhook URL from Certifai
4. Set the Secret token to the webhook secret from Certifai
5. Under Trigger, check:
   • Push events -- for automatic scans on push
   • Merge request events -- for PR security reviews
6. Click Add webhook

PR Review Flow

When a pull request (or merge request) is opened or updated, the following happens:

1. Your Git provider sends a webhook event to Certifai
2. Certifai checks out the PR branch and runs a targeted scan on the changed files
3. Findings specific to the changes in the PR are identified
4. Certifai posts a review comment on the PR summarizing:
   • Number of new findings introduced by the changes
   • Severity breakdown
   • Details for each finding including file, line, and remediation guidance

This gives developers immediate security feedback in their pull request workflow, before code is merged.

::: tip PR reviews focus only on changes introduced in the pull request, not the entire codebase. This keeps reviews relevant and actionable. :::

Events to Select

Here is a summary of which events to enable for each feature:

Feature	Gitea	GitHub	GitLab
Scan on push	Push Events	Pushes	Push events
PR reviews	Pull Request Events	Pull requests	Merge request events

You can enable one or both depending on your workflow.

::: warning Make sure the webhook secret matches exactly between your Git provider and Certifai. Requests with an invalid signature are rejected. :::