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

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:

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.

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

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

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.

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