Pre-Commit Webhooks API Reference

This reference documents the public API contract for pre-commit webhooks. Use it with the Pre-Commit Webhooks Guide, 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 to enable the feature for your organization.

As of September 2026, the Change Validation API accepts edit-validation callbacks and callbacks for Console-initiated creations. Refer to Availability limitations for creation and recovery API support.

Authentication and request conventions

Requests to the Change Validation API

Authenticate requests to Statsig with a Console API key in the STATSIG-API-KEY header. Create and manage Console API keys from the Statsig API keys page.

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

Creation-validation verdicts and progress updates require a write-capable key with permission to modify the project. Edit-validation callbacks accept read-only and write-capable keys.

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:

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:

Supported edit variants

Rules changes

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

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:

{
  "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.

Example, abbreviated:

{
  "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.

Both old_settings and new_settings use this object shape.

Experiment changes

Experiment payloads use experiment_name and don't include change_id.

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:

Example, abbreviated:

{
  "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.

Creation validation callback requirements

Creation callbacks require creationValidationAttemptID; edit callbacks don't.

Each creation-validation retry generates a new creation_validation_attempt_id. Use the value from the latest webhook payload so that a callback for an earlier retry can't affect the current validation.

Submit a validation result

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

Request body

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

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

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."
  }'

Example: approve a creation

Use the values from the creation webhook payload:

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",
    "creationValidationAttemptID": "attempt_01HXYZ",
    "validated": true,
    "message": "The creation passed policy validation."
  }'

To reject the creation, send validated: false with the same reviewID and current creationValidationAttemptID. Statsig keeps the resource held and displays the feedback.

Response

Successful requests return HTTP 200:

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

Update the validation message

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

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

Request body

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."
  }'

Example request body for PATCH /console/v1/change_validation/message when updating creation-validation progress:

{
  "reviewID": "review_01HXYZ",
  "creationValidationAttemptID": "attempt_01HXYZ",
  "message": "Running creation policy checks."
}

Successful requests return HTTP 200:

{
  "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:

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

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

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.

Creation callbacks distinguish these HTTP 409 messages:

Availability limitations

Creation validation API support

As of September 2026, the public API contract doesn't support creation-validation payload schemas. Use the Statsig Console UI for creation validation; public API support for initiating creation validation isn't available yet. Refer to the main guide 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 creation and recovery API support remains unreleased. Public Console API support is planned for a future release. Disabling creation validation stops new validations but doesn't release resources already held for validation.

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.