---
title: "Pre-Commit Webhooks API Reference"
description: "Reference for public pre-commit webhook payloads, authentication, Change Validation API callbacks, responses, errors, and availability."
product: general
token_estimate: 3738
---
# Pre-Commit Webhooks API Reference

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

This reference documents the public API contract for pre-commit webhooks. Use it with the [Pre-Commit Webhooks Guide](https://docs.statsig.com/guides/pre-commit-webhooks), which explains feature access, configuration, validation lifecycle, and operations.

## Availability

Pre-commit webhooks are feature gated at the organization level. Contact your Statsig account team or [Statsig Support](https://docs.statsig.com/support-options) to enable the feature for your organization.

As of September 2026, the public Console API reference covers edit-validation callbacks. The public API contract doesn't support creation-validation payload schemas, creation attempt identifiers, or creation-validation recovery operations yet. Refer to [Availability limitations](#availability-limitations) for details.

## Authentication and request conventions

### Requests to the Change Validation API

Authenticate requests to Statsig with a write-capable Console API key in the `STATSIG-API-KEY` header. Create and manage Console API keys from the [Statsig API keys page](https://console.statsig.com/api_keys).

```bash
STATSIG-API-KEY: console-xxxxxxxxxxxxxxxx
Content-Type: application/json
```

Read-only keys can't submit validation results or update validation messages.

The Console API applies approximate rate limits of 100 requests per 10 seconds and 900 requests per 15 minutes. Design validators to avoid unnecessary retries and handle rate-limit responses gracefully.

### Requests from Statsig to your webhook

Statsig sends webhook requests to the HTTPS URL configured in the Statsig Console. Requests use `POST` with a JSON body and include the following headers:

| Header | Description |
| --- | --- |
| `Content-Type` | `application/json` |
| `x-statsig-webhook-key` | The webhook key configured for the organization. Use it to authenticate requests from Statsig. |
| `x-statsig-project-name` | The Statsig project name. Statsig sends this header when a webhook key is configured. |

If no webhook key is configured, Statsig omits both custom headers. Configure a webhook key and validate it before processing the request.

The webhook endpoint must return a 2xx response within 2 minutes. This response acknowledges delivery only; it doesn't approve or reject the change. Submit the validation verdict separately through the Change Validation API.

Webhook payload fields use `snake_case`. Change Validation API fields use `camelCase`.

## Webhook payload reference

### Common fields

The following fields appear in the public edit-validation payloads:

| Field | Type | Description |
| --- | --- | --- |
| `review_id` | string | Identifier of the Statsig review being validated. |
| `change_id` | string | Identifier for the proposed configuration change. Present for gate, dynamic config, segment, and holdout payloads. Experiment payloads don't include this field. |
| `submitter` | string | Email address or actor identifier for the user who submitted the change. |
| `committer` | string | Email address or actor identifier for the user committing the change. |
| `config_type` | string | Resource type: `gate`, `dynamic_config`, `segment`, `holdout`, or `experiment`. |
| `config_name` | string | Name of the gate, dynamic config, segment, or holdout. Not used for experiment payloads. |
| `experiment_name` | string | Name of the experiment. Used instead of `config_name` for experiment payloads. |
| `type` | string | Discriminator for the change operation. Refer to the supported variants below. |

### Supported edit variants

| `config_type` | `type` | Payload-specific fields |
| --- | --- | --- |
| `gate`, `dynamic_config`, `segment` | `rules` | `diffs`, `old_config`, `new_config` |
| `gate`, `dynamic_config`, `segment`, `experiment` | `update_target_apps` | `old_target_apps`, `new_target_apps` |
| `holdout` | `holdout_settings` | `old_settings`, `new_settings` |
| `experiment` | `update_allocation` | `old_allocation`, `new_allocation`, `old_experiment` |
| `experiment` | `start_experiment` | `new_allocation`, `old_experiment` |
| `experiment` | `ship_experiment` | `group`, `old_experiment`, `decision_reason` |
| `experiment` | `abandon_experiment` | `old_experiment`, `decision_reason` |
| `experiment` | `update_experiment_settings` | `old_settings`, `new_settings`, `old_experiment`, `new_experiment` |

### Rules changes

`rules` payloads describe changes to feature gates, dynamic configs, or segments.

| Field | Type | Description |
| --- | --- | --- |
| `diffs` | array or `null` | Structured differences between the previous and proposed rules. |
| `old_config` | object, optional in the contract | The resource state before the change. |
| `new_config` | object, optional in the contract | The proposed resource state. |

The nested resource objects use the corresponding Statsig resource representation. The Console API resource definitions maintain their complete schemas, so this reference doesn't duplicate them.

Example, abbreviated:

```json
{
  "review_id": "review_01HXYZ",
  "change_id": "snapshot_01HXYZ",
  "submitter": "submitter@example.com",
  "committer": "committer@example.com",
  "config_type": "gate",
  "config_name": "checkout_gate",
  "type": "rules",
  "diffs": [],
  "old_config": {
    "name": "checkout_gate"
  },
  "new_config": {
    "name": "checkout_gate"
  }
}
```

### Target application changes

`update_target_apps` payloads contain the previous and proposed target application names.

| Field | Type | Description |
| --- | --- | --- |
| `old_target_apps` | array of strings | Target applications before the change. |
| `new_target_apps` | array of strings | Target applications after the change. |

Example, abbreviated:

```json
{
  "review_id": "review_01HXYZ",
  "change_id": "snapshot_01HXYZ",
  "submitter": "submitter@example.com",
  "committer": "committer@example.com",
  "config_type": "dynamic_config",
  "config_name": "checkout_config",
  "type": "update_target_apps",
  "old_target_apps": ["web"],
  "new_target_apps": ["web", "ios"]
}
```

### Holdout setting changes

`holdout_settings` payloads contain the previous and proposed holdout settings.

| Field | Type | Description |
| --- | --- | --- |
| `isGlobal` | boolean | Whether the holdout is global. |
| `globalApplyToGates` | boolean | Whether a global holdout applies to gates. |
| `globalApplyToExperiments` | boolean | Whether a global holdout applies to experiments. |
| `globalApplyToLayers` | boolean | Whether a global holdout applies to layers. |
| `passPercent` | number | Holdout pass percentage. |
| `gates` | array of strings | Names of gates associated with the holdout. |
| `experiments` | array of strings | Names of experiments associated with the holdout. |
| `layers` | array of strings | Names of layers associated with the holdout. |
| `targetingGateName` | string or `null` | Targeting gate name, if configured. |

Both `old_settings` and `new_settings` use this object shape.

### Experiment changes

Experiment payloads use `experiment_name` and don't include `change_id`.

| `type` | Fields | Description |
| --- | --- | --- |
| `update_allocation` | `old_allocation`, `new_allocation`, `old_experiment` | Changes the experiment allocation. |
| `start_experiment` | `new_allocation`, `old_experiment` | Starts an experiment. |
| `ship_experiment` | `group`, `old_experiment`, `decision_reason` | Ships a selected experiment group. |
| `abandon_experiment` | `old_experiment`, `decision_reason` | Abandons an experiment. |
| `update_target_apps` | `old_target_apps`, `new_target_apps` | Changes the experiment's target applications. |
| `update_experiment_settings` | `old_settings`, `new_settings`, `old_experiment`, `new_experiment` | Changes experiment settings. |

The `old_experiment` and `new_experiment` objects use the corresponding Statsig experiment representation. The settings objects contain experiment groups, allocation, targeting gate, and inline targeting rules.

Experiment settings use the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `groups` | array of objects | Experiment groups. Each group contains `name`, `parameterValuesJSON`, and `size`. |
| `allocation` | number | Experiment allocation percentage. |
| `targetingGateID` | string or `null` | Targeting gate identifier, if configured. |
| `inlineTargetingRulesJSON` | string or `null` | Inline targeting rules, if configured. |

Example, abbreviated:

```json
{
  "review_id": "review_01HXYZ",
  "submitter": "submitter@example.com",
  "committer": "committer@example.com",
  "config_type": "experiment",
  "experiment_name": "checkout_experiment",
  "type": "ship_experiment",
  "group": "variant_a",
  "old_experiment": {
    "name": "checkout_experiment"
  },
  "decision_reason": "Variant A met the success criteria."
}
```

## Change Validation API

The Change Validation API records the verdict produced by your validation service. It's a callback endpoint, not a status-retrieval or polling endpoint.

### Submit a validation result

```bash
POST https://statsigapi.net/console/v1/change_validation
```

#### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reviewID` | string | Yes | The `review_id` from the webhook payload. |
| `validated` | boolean | Yes | `true` approves the edit; `false` rejects it. |
| `message` | string | No | Feedback displayed to the user. |
| `debugLinks` | array of objects | No | Links to relevant logs or diagnostic information. Each object contains required `title` and `url` strings. |
| `releasePipelineIDForCommit` | string or `null` | No | Release pipeline behavior for an approved gate or dynamic config edit. Omit this field to use the resource's configured behavior; send `null` to explicitly disable a release pipeline. |

Send `releasePipelineIDForCommit` only when approving an edit to a gate or dynamic config. Don't send it for experiments, segments, holdouts, or rejected validations. Statsig doesn't support release pipeline overrides for creation validation.

Statsig records `debugLinks` with an approved validation result. Provide them when `validated` is `true`. Statsig doesn't use them to approve or reject the change.

#### Example: approve a change

```bash
curl --request POST \
  --url https://statsigapi.net/console/v1/change_validation \
  --header 'STATSIG-API-KEY: console-xxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "reviewID": "review_01HXYZ",
    "validated": true,
    "message": "The change passed policy validation.",
    "debugLinks": [
      {
        "title": "Validation run",
        "url": "https://validator.example.com/runs/01HXYZ"
      }
    ]
  }'
```

#### Example: reject a change

```bash
curl --request POST \
  --url https://statsigapi.net/console/v1/change_validation \
  --header 'STATSIG-API-KEY: console-xxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "reviewID": "review_01HXYZ",
    "validated": false,
    "message": "The change violates the production rollout policy."
  }'
```

#### Response

Successful requests return HTTP `200`:

```json
{
  "message": "Validation status updated successfully"
}
```

### Update the validation message

Use this endpoint to publish progress or replace the message shown while validation is pending.

```bash
PATCH https://statsigapi.net/console/v1/change_validation/message
```

#### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reviewID` | string | Yes | The `review_id` from the webhook payload. |
| `message` | string | No | The current validation progress or status message. |

```bash
curl --request PATCH \
  --url https://statsigapi.net/console/v1/change_validation/message \
  --header 'STATSIG-API-KEY: console-xxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "reviewID": "review_01HXYZ",
    "message": "Running policy and integration checks."
  }'
```

Successful requests return HTTP `200`:

```json
{
  "message": "Validation message updated successfully"
}
```

Send message updates only while the validation is pending. The endpoint doesn't approve, reject, or retrieve the validation result.

## Errors and status handling

Console API errors use this general shape:

```json
{
  "status": 400,
  "message": "Invalid review ID"
}
```

The response may also include an `errors` field with validation details.

| HTTP status | Common causes | Recommended action |
| --- | --- | --- |
| `400 Bad Request` | Invalid request body, invalid review ID, review isn't pending, or an invalid release-pipeline combination. | Correct the request and submit it for the active pending review. |
| `401 Unauthorized` | Missing, invalid, or inactive `STATSIG-API-KEY`. | Use an active Console API key. |
| `403 Forbidden` | The key is read-only or doesn't have permission to modify the project. | Use a write-capable key with the required project permissions. |
| `500 Internal Server Error` | Statsig could not complete a server-side operation after accepting the validation result. | Check the response message, avoid blindly repeating requests, and contact Statsig Support if the problem persists. |

The public API doesn't provide a polling endpoint for validation status. Track the `reviewID` in your validator and use the Statsig Console to inspect the resulting status and message.

## Availability limitations

### Creation validation API support

As of September 2026, the public API contract doesn't support creation-validation payload schemas or `creationValidationAttemptID`. Don't build against the runtime-only creation fields or assume that creation-validation callback behavior is available through the public API. Refer to the [main guide](https://docs.statsig.com/guides/pre-commit-webhooks) for the creation-validation lifecycle and contact Statsig for current availability.

### Creation-validation recovery

As of September 2026, you can use retry, discard, and bypass recovery actions for creation validation only in the Statsig Console. Statsig excludes the corresponding internal routes from the public OpenAPI specification. Don't use them as public API integrations. Public Console API support is planned for a future release.

### Configuration management

The public API reference doesn't include an endpoint for configuring the webhook URL, webhook key, or initial message. Configure these values in the Statsig Console under _Settings > Product Configuration > General_.

### Resource coverage

The public edit-validation payload contract covers gates, dynamic configs, segments, holdouts, and experiments. As of September 2026, the public API contract doesn't include layer creation payloads or other creation-validation payloads.