# 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.
:::