Skip to main content
This functionality is only available in Flipt v2 Pro. Learn more about our commercial license or purchase a monthly or annual license.
A webhook is an HTTP notification from your Git provider. When you push or merge changes to a tracked branch, Flipt fetches the repository without waiting for the next poll. Use webhooks when you need changes from Git to reach Flipt quickly, such as when you disable a flag during an incident. To configure your provider, follow the webhook setup guide.

​
How synchronization works

Your Git provider sends a push event to POST /api/v2/webhooks/{environment}. Flipt authenticates the request and makes sure that the event affects a branch tracked by the environment’s storage. For a matching event, Flipt schedules a Git fetch and returns 202 Accepted. The fetch updates all environments that share that repository within the Flipt instance. Flipt combines overlapping requests for the same repository to avoid concurrent webhook fetches. Flipt reads flag state from Git. The webhook payload only triggers the fetch. A merge triggers synchronization through the resulting push event on the target branch. You do not need to subscribe to pull request or merge request events.
A 202 response means that Flipt scheduled a fetch. It does not mean that synchronization completed. Polling continues at the configured poll_interval and remains the fallback for missed deliveries or failed fetches.
Webhooks update the Flipt server’s flag state. Your application’s update timing also depends on its SDK polling or streaming configuration.

​
Configuration

Configure webhook.secret under an environment’s scm block. The environment must already use storage with a Git remote. This example assumes that the github storage and credentials are configured through Git sync.
The endpoint for this example is /api/v2/webhooks/production. The path uses the configured environment name, which defaults to the production key. If you explicitly set name: live, use /api/v2/webhooks/live instead. The secret is required and must match the value in your Git provider’s webhook configuration. Use a separate random secret for webhook authentication, rather than your Git access token. You can supply a literal value, an environment substitution, or a secret reference:
Flipt resolves the secret at startup. If the resolved value is empty, Flipt refuses to start. Restart Flipt after you change the secret. Without a Pro license, Flipt does not register the webhook endpoint and logs a warning.

​
Supported providers

The environment’s scm.type selects how Flipt authenticates and parses deliveries. HMAC-SHA256 signatures let Flipt authenticate the request body with the shared secret. Your provider generates the signature automatically. The endpoint uses provider authentication instead of a Flipt API token. Use HTTPS and allow your Git provider to reach the endpoint through your firewall or reverse proxy. Preserve the request body and authentication headers when forwarding deliveries.

​
Responses

Flipt accepts request bodies up to 5 MiB. Only a 202 response schedules a fetch. Unknown environments and environments without webhook configuration return the same 401 response as invalid authentication.

​
Monitoring

Flipt exposes these Prometheus metrics through its metrics endpoint: Request results are accepted, ignored, unauthorized, not_found, or invalid. Unknown environments use environment="unknown" and scm="unknown" to avoid creating labels for arbitrary request paths. If a delivery receives 202 but flag state does not update, inspect Flipt’s logs and the fetch error counter. A successful delivery can still be followed by a Git authentication or network failure.