Set Up Webhooks

This functionality is only available in Flipt v2 Pro. Learn more about our commercial license or purchase a monthly or annual license.

This guide connects your Git provider to Flipt’s incoming webhook endpoint. After setup, a push or merge to a tracked branch triggers a Git fetch without waiting for the next poll.

Prerequisites

A running Flipt v2 server with an active Pro or trial license and webhook support.
An environment configured with Git sync and SCM integration.
Permission to manage webhooks or service hooks for your Git repository.
An HTTPS URL for Flipt that your Git provider can reach.

1. Create a webhook secret

Generate a random secret with OpenSSL:

openssl rand -hex 32

Store the result securely. Set FLIPT_WEBHOOK_SECRET to this value in the environment of the Flipt server process. You also need this value when you configure your Git provider. Use a separate value from the access token that Flipt uses to read and write your repository.

2. Configure Flipt

Add the webhook block to your existing environment’s scm configuration. This example uses the production environment and GitHub:

environments:
  production:
    storage: github
    default: true
    scm:
      type: github
      credentials: github
      webhook:
        secret: ${env:FLIPT_WEBHOOK_SECRET}

Keep your existing storage identifier and SCM credentials. For another provider, use its SCM type. You can also use a secret reference instead of an environment variable. Restart your Flipt server with the updated configuration. Make sure that FLIPT_WEBHOOK_SECRET is available to the server process. Flipt refuses to start if the webhook secret resolves to an empty value. The webhook endpoint for this example is https://flipt.example.com/api/v2/webhooks/production. Replace flipt.example.com with your Flipt host. The final path segment must match the environment’s configured name, which defaults to its YAML key. If your existing environment sets name: Production, use /api/v2/webhooks/Production, with the same capitalization.

3. Configure your Git provider

Use the endpoint URL from the previous step and the same secret that you configured in Flipt. Keep TLS certificate verification enabled.

GitHub
GitLab
Gitea
Bitbucket
Azure DevOps

Open your repository’s Settings > Webhooks and select Add webhook.
Set Payload URL to your Flipt webhook endpoint.
Set Content type to application/json.
Set Secret to your webhook secret.
Select Just the push event and keep Active selected.
Select Add webhook.

GitHub sends a ping event after creation. Flipt returns 200 OK for an authenticated ping without fetching the repository.See GitHub’s webhook documentation for details.

Open your project’s Settings > Webhooks and add a webhook.
Set URL to your Flipt webhook endpoint.
Set Secret token to your webhook secret.
Select Push events. If you filter branches, include the branches that Flipt tracks.
Save the webhook.

Flipt authenticates GitLab deliveries through X-Gitlab-Token. Configure the Secret token field even if your GitLab version also offers a signing token. A signing token alone does not authenticate deliveries to Flipt.

See GitLab’s webhook documentation for details.

Open your repository’s Settings > Webhooks and add a Gitea webhook.
Set Target URL to your Flipt webhook endpoint.
Select POST and the application/json content type.
Set Secret to your webhook secret.
Select push events, keep the webhook active, and save it.

Use the native Gitea webhook type so that Gitea sends the signature and event headers that Flipt expects.See Gitea’s webhook documentation for details.

For Bitbucket Cloud:

Open your repository’s settings and select Webhooks > Add webhook.
Enter a title and set URL to your Flipt webhook endpoint.
Set Secret to your webhook secret.
Select Repository push, keep the webhook active, and save it.

For Bitbucket Server/Data Center, add a repository webhook with the same endpoint and secret. Select the repository push event that sends repo:refs_changed deliveries.Both variants use scm.type: bitbucket in Flipt. Make sure that your Bitbucket version supports webhook secrets and sends an HMAC-SHA256 signature in X-Hub-Signature.See Bitbucket Cloud’s webhook documentation for details.

Open Project settings > Service hooks and create a subscription.
Select Web Hooks as the service.
Select Code pushed as the trigger and choose your repository.
If you filter branches, include the branches that Flipt tracks.
Set URL to your Flipt webhook endpoint.
Configure Basic authentication with a username, such as flipt, and your webhook secret as the password.
Finish creating the subscription.

Flipt checks the Basic authentication password against webhook.secret. Flipt does not require a particular username. Use scm.type: azure in your Flipt configuration.See Azure DevOps’ webhook documentation for details.

4. Test synchronization

Make a flag change in your Git repository and push it to the branch that Flipt tracks. You can also merge a pull request or merge request that changes a flag on that branch. Open your provider’s webhook delivery history and inspect the push delivery. A matching push returns 202 Accepted. Make sure that the changed flag state appears in Flipt. A 200 OK response means that Flipt authenticated the delivery but did not schedule a fetch. Provider test buttons can send pings, unrelated events, or a branch that Flipt does not track. Use a real push to test synchronization.

Keep poll_interval configured as a fallback. In a deployment with multiple replicas, a webhook updates the instance that receives it. Deliver to each replica for prompt updates across the deployment. A load balancer that sends each request to one replica does not broadcast the update to the others.

Troubleshooting

Symptom	Action
No delivery reaches Flipt	Make sure that your provider can reach the HTTPS endpoint and that your proxy forwards the path and authentication headers.
`404 Not Found`	Make sure that the URL is correct, your Flipt build includes webhook support, and a Pro license and webhook configuration are active.
`401 Unauthorized`	Make sure that the configured environment name and secrets match. For GitLab, use Secret token. For Azure DevOps, use the secret as the Basic authentication password.
`200 OK` but no update	Make sure that the delivery is a push event for a tracked branch, rather than a ping or tag event.
`202 Accepted` but no update	Inspect Flipt’s logs and webhook metrics for Git fetch failures. Make sure that repository credentials still work.
Flipt fails to start	Make sure that the webhook secret is nonempty after environment or secret resolution.

For payload limits, authentication headers, and all response codes, see the webhook reference.

Getting Started

Pro Features

Configuration

Integration

CLI

Guides

Tooling

Set Up Webhooks

Prerequisites

1. Create a webhook secret

2. Configure Flipt

3. Configure your Git provider

4. Test synchronization

Troubleshooting

​Prerequisites

​1. Create a webhook secret

​2. Configure Flipt

​3. Configure your Git provider

​4. Test synchronization

​Troubleshooting

Prerequisites

1. Create a webhook secret

2. Configure Flipt

3. Configure your Git provider

4. Test synchronization

Troubleshooting