Pre-commit Webhooks allow you to integrate external validation into your change approval workflow. This enables you to:

* Route changes through internal approval systems
* Run automated tests before changes go live
* Enforce custom business logic or compliance checks
* Integrate with CI/CD pipelines

## How pre-commit webhooks work

When a Statsig user submits a change for review and a reviewer approves it, clicking **Commit Changes** triggers your configured webhook. Statsig sends the change details to your endpoint. Your endpoint validates the change (for example, runs tests or checks policies) and responds to Statsig with either an approval or a rejection. The response determines whether the user can commit the change or whether it remains blocked.

## Setup instructions

### Step 1: Configure your webhook endpoint

Your webhook endpoint must:

* Accept POST requests from Statsig
* Process the change payload (refer to the format below)
* Call the Change Validation API to approve or reject

Refer to the [Change Validation API documentation](/console-api/introduction) for implementation details.

### Step 2: Configure Statsig console settings

Navigate to **Settings** → **Product Configuration** → [**General**](https://console.statsig.com/settings/products):

1. **Webhook URL**: The endpoint where Statsig sends change notifications
2. **Webhook Key**: A secret key sent in the `x-statsig-webhook-key` header for authentication
3. **Initial Message**: A message shown to users while validation is in progress
   * Example: "Your change is being validated by our CI/CD system. This may take up to 2 minutes..."

{% figure %}
<img src="/images/guides/setting-up-reviews/49c408da-0910-4a90-9ee3-7d1e114c9013.png" alt="Webhook URL and initial message configuration" width="495" />
{% /figure %}

{% figure %}
<img src="/images/guides/setting-up-reviews/a01617b2-3bb0-4f20-a505-b9318dd220a7.png" alt="Webhook verification key configuration" width="497" />
{% /figure %}

## Usage instructions

### Step 3: Send a webhook payload

Every payload has these fields at a minimum:

```json
{
  "review_id": "string",           // Required for API response
  "submitter": "user@example.com", // Who created the review
  "committer": "user@example.com", // Who is committing the change
  "config_type": "gate | dynamic_config | segment | experiment",
  "config_name": "string",         // For gates, configs, segments
  "experiment_name": "string",     // For experiments
  "type": "string"                 // Change type (see below)
}
```

Currently, only changes to gates, dynamic configs, segments, and experiments trigger pre-commit webhooks, and only the following changes:

* `rules`: Updating rules (for gates, dynamic configs, segments)
  * contains payloads `old_config` and `new_config` with the same format returned by the console API for the entity type (e.g. [/api-reference/gates/read-gate](/api-reference/gates/read-gate) for gates)
* `update_target_apps`: Updating target applications
* `update_allocation`: Changing the pass percentage of an ongoing experiment
* `start_experiment`
* `ship_experiment`
* `abandon_experiment`
* `update_experiment_settings`: Changing settings of an ongoing experiment
  * contains payloads `old_experiment` and `new_experiment` with the same format returned by the [Console API](/console-api/introduction)

### Step 4: Respond to webhooks

Your system must call the Change Validation API to approve or reject the change:

**Endpoint:** `POST https://statsigapi.net/console/v1/change_validation`

When responding to validation, set the `message` field to provide a message to the user. Set the message after validation completes, or provide progressive updates while validation is running.

```json
{
  "reviewID": "review_123",
  "message": "⏳ Running tests... (45/150 complete)"
}
```

**What Users See**

When a review is pending validation, users see:

* **Title**: "Changes to this config have been reviewed and are pending validation"
* **Description**:
  * The company-level `precommit_webhook_message` (if set in console settings)
  * The review-specific `precommit_message` (if your webhook has set it)

## Bypassing validation

Project Admins can grant the "Bypass Pre-commit Webhook" permission to specific roles. Users with this permission see a "Commit Changes (Bypass Validation)" option that lets them skip webhook validation entirely.

## Best practices

1. **Respond quickly**: You have 2 minutes before the request times out.
2. **Include debug links**: Help users troubleshoot failures quickly.
3. **Use progressive updates**: Keep users informed during long validations.
4. **Set a helpful initial message**: Explain what is happening and the expected wait time.
5. **Handle errors gracefully**: If your validation system is unavailable, consider auto-approving or notifying users.