> ## Documentation Index
> Fetch the complete documentation index at: https://personal-ce79cb71.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BugViper Webhook API — GitHub Event Configuration Guide

> Configure BugViper webhook endpoints to receive GitHub PR review events, including HMAC-SHA256 signature verification for secure payload delivery.

BugViper receives GitHub webhook events to trigger code reviews and track PR activity. These endpoints are called by GitHub, not by you directly — but you need to configure them when setting up the GitHub App. Once registered, GitHub will POST event payloads to BugViper automatically whenever pull request activity occurs in your connected repositories.

<Note>
  These endpoints are public and do not require Firebase authentication. They are secured instead via HMAC-SHA256 signature verification — GitHub signs every payload with your configured webhook secret, and BugViper rejects any request whose signature does not match.
</Note>

***

## POST /api/v1/webhook/onComment

The main webhook receiver for all GitHub PR and repository events. When BugViper receives a valid payload on this endpoint, it inspects the event type and dispatches the appropriate action — queuing a code review, updating PR state, or handling an app installation.

**Authentication:** GitHub HMAC-SHA256 signature delivered in the `X-Hub-Signature-256` request header. BugViper validates this signature against your configured webhook secret before processing any payload.

### Handled Event Types

| Event                        | Action                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `issue_comment`              | Parses the comment body for BugViper bot commands and queues a review if a valid command is found |
| `pull_request`               | Tracks PR lifecycle events (opened, closed, merged)                                               |
| `push`                       | Records push activity for blast-radius tracking                                                   |
| `installation`               | Handles GitHub App installation and uninstallation                                                |
| `pull_request_review_thread` | Tracks review thread resolution status                                                            |

### Bot Commands

When an `issue_comment` event arrives, BugViper checks whether the comment contains a recognized command:

| Comment                                       | Action                                                           |
| --------------------------------------------- | ---------------------------------------------------------------- |
| `@bugviper review` or `@bugviper full review` | Triggers a full AI-powered review in normal or deep mode         |
| `@bugviper run lint` or `@bugviper lint`      | Triggers a fast static analysis run using the configured linters |

### Configuration

Set this URL as the **Webhook URL** in your GitHub App settings:

```
https://your-domain.com/api/v1/webhook/onComment
```

***

## POST /api/v1/webhook/marketplace

Receives GitHub Marketplace purchase and subscription lifecycle events. BugViper uses these events to update account plan status in response to Marketplace activity.

**Authentication:** GitHub HMAC-SHA256 signature delivered in the `X-Hub-Signature-256` request header. BugViper validates this signature against your configured Marketplace webhook secret before processing any event.

### Handled Event Types

| Event                      | Description                                                             |
| -------------------------- | ----------------------------------------------------------------------- |
| `purchased`                | A new Marketplace subscription was created                              |
| `cancelled`                | An existing subscription was cancelled                                  |
| `changed`                  | A subscription was upgraded or downgraded                               |
| `pending_change`           | A plan change is pending and will take effect at the next billing cycle |
| `pending_change_cancelled` | A previously pending plan change was cancelled before it took effect    |

***

## Webhook Setup

Follow these steps to register BugViper's webhook with your GitHub App:

<Steps>
  <Step title="Open your GitHub App settings">
    Go to **GitHub → Settings → Developer settings → GitHub Apps** and select your BugViper app.
  </Step>

  <Step title="Set the Webhook URL">
    In the **Webhook** section, enter your BugViper webhook URL:

    ```
    https://your-domain.com/api/v1/webhook/onComment
    ```
  </Step>

  <Step title="Set the Webhook Secret">
    Enter a strong random string in the **Webhook secret** field and save the same value in your BugViper deployment configuration. GitHub uses this secret to sign every outbound payload with HMAC-SHA256, and BugViper uses it to verify authenticity before processing.
  </Step>

  <Step title="Select the required events">
    Under **Subscribe to events**, enable the following:

    * Issue comments
    * Pull requests
    * Pushes
    * Installations
    * Pull request review threads
  </Step>

  <Step title="Save your changes">
    Click **Save changes**. GitHub will immediately begin delivering matching events to your webhook URL. You can verify delivery in the **Recent Deliveries** tab of your GitHub App settings.
  </Step>
</Steps>

<Tip>
  During local development, use a tool like [ngrok](https://ngrok.com) to expose your local server to the internet and receive live GitHub webhook payloads for testing.
</Tip>