docs: document incoming webhooks for Flipt v2 Pro

docs/docs.json

@@ -42,7 +42,6 @@
               },
               {
                 "group": "Pro Features",
-                "tag": "NEW",
                 "icon": "crown",
                 "pages": [
                   "v2/pro",
@@ -55,6 +54,7 @@
                 "pages": [
                   "v2/configuration/overview",
                   "v2/configuration/environments",
+                  "v2/webhooks/overview",
                   "v2/configuration/storage",
                   "v2/configuration/secrets",
                   "v2/configuration/commit-signing",
@@ -154,6 +154,7 @@
                           "v2/guides/operations/environments/git-repository-initialization",
                           "v2/guides/operations/environments/git-sync",
                           "v2/guides/operations/environments/git-scm",
+                          "v2/guides/operations/environments/webhooks",
                           "v2/guides/operations/environments/commit-signing-setup"
                         ]
                       }

docs/v2/configuration/environments.mdx

@@ -133,6 +133,12 @@ Environments can be configured to use a single Source Control Management (SCM) p
 
 See the [Git SCM Integration](/v2/guides/operations/environments/git-scm) guide for more information on how to configure Flipt v2 to use a SCM provider.
 
+### Webhooks
+
+With Flipt Pro, you can configure incoming webhooks to fetch changes from Git after a push or merge to a tracked branch. Polling continues as a fallback.
+
+Add `webhook.secret` under the environment's `scm` block. See the [webhook reference](/v2/webhooks/overview) for configuration and the [setup guide](/v2/guides/operations/environments/webhooks) for provider instructions.
+
 ### Credentials
 
 Configuring an SCM provider requires a set of credentials to be provided. These credentials are configured via the same mechanism as the [remote storage credential configuration](/v2/configuration/storage#credentials).

docs/v2/configuration/overview.mdx

@@ -227,6 +227,18 @@ Environments configuration allows you to create isolated feature flag namespaces
 | environments.[id].scm.api_url     | The API URL of the SCM provider to use (optional)                                  |         | v2.0.0 |
 | environments.[id].scm.credentials | The id of the credentials to use for the SCM provider                              |         | v2.0.0 |
 
+#### Incoming Webhooks
+
+Incoming webhooks require Flipt Pro and an environment with a Git remote and SCM configuration. Add a `webhook` block under the environment's `scm` block to fetch changes after a push or merge to a tracked branch. Polling continues as a fallback.
+
+| Property                             | Description                                                                                        | Default | Since   |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------- | ------- | ------- |
+| environments.[id].scm.webhook.secret | Shared secret for authenticating incoming webhooks. Required when the webhook block is configured. | None    | v2.14.0 |
+
+The secret accepts a literal value, an [environment substitution](#environment-substitution-and-secret-references), or a [secret reference](/v2/configuration/secrets#secret-reference-syntax). Flipt refuses to start if the secret resolves to an empty value.
+
+See [Webhooks](/v2/webhooks/overview) for configuration examples and endpoint details, or follow the [webhook setup guide](/v2/guides/operations/environments/webhooks) for provider instructions.
+
 ### User Interface
 
 User interface configuration customizes the appearance and behavior of the Flipt web UI.

docs/v2/guides/operations/environments/git-scm.mdx

@@ -370,6 +370,10 @@ Start or restart your Flipt server with the updated configuration. Flipt will no
 
 ![Merge Proposals](/v2/images/guides/operations/environments/merge_proposals.png)
 
+## Receive Changes with Webhooks
+
+To fetch changes after a push or merge without waiting for the next poll, configure [incoming webhooks](/v2/webhooks/overview). The [webhook setup guide](/v2/guides/operations/environments/webhooks) covers each supported provider.
+
 ## 3. Troubleshooting
 
 ### Common Issues

docs/v2/guides/operations/environments/git-sync.mdx

@@ -122,6 +122,10 @@ Start or restart your Flipt server with the updated configuration. Flipt will no
 - Make sure the local path is writable by the Flipt process.
 - Check Flipt logs for any sync or authentication errors.
 
+## Sync Changes with Webhooks
+
+With Flipt Pro, you can use [incoming webhooks](/v2/webhooks/overview) to fetch changes after a push or merge without waiting for the next poll. Follow the [webhook setup guide](/v2/guides/operations/environments/webhooks) to connect your Git provider. Polling remains the fallback for missed deliveries.
+
 ## Conclusion
 
 This guide showed how to configure Flipt to sync your flag state to a GitHub repository using a Personal Access Token (PAT) for authentication.

docs/v2/guides/operations/environments/webhooks.mdx

@@ -0,0 +1,161 @@
+---
+title: Set Up Webhooks
+description: Configure your Git provider to trigger Flipt synchronization after a push or merge.
+---
+
+import V2Pro from "/snippets/v2-pro.mdx";
+
+<V2Pro />
+
+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](/v2/licensing) and webhook support.
+- An environment configured with [Git sync](/v2/guides/operations/environments/git-sync) and [SCM integration](/v2/guides/operations/environments/git-scm).
+- 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:
+
+```bash
+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:
+
+```yaml highlight={8-9}
+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](/v2/webhooks/overview#supported-providers). You can also use a [secret reference](/v2/webhooks/overview#configuration) 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.
+
+<Tabs>
+<Tab title="GitHub">
+
+1. Open your repository's **Settings > Webhooks** and select **Add webhook**.
+2. Set **Payload URL** to your Flipt webhook endpoint.
+3. Set **Content type** to `application/json`.
+4. Set **Secret** to your webhook secret.
+5. Select **Just the push event** and keep **Active** selected.
+6. 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](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks) for details.
+
+</Tab>
+<Tab title="GitLab">
+
+1. Open your project's **Settings > Webhooks** and add a webhook.
+2. Set **URL** to your Flipt webhook endpoint.
+3. Set **Secret token** to your webhook secret.
+4. Select **Push events**. If you filter branches, include the branches that Flipt tracks.
+5. Save the webhook.
+
+<Note>
+  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.
+</Note>
+
+See [GitLab's webhook documentation](https://docs.gitlab.com/user/project/integrations/webhooks/) for details.
+
+</Tab>
+<Tab title="Gitea">
+
+1. Open your repository's **Settings > Webhooks** and add a **Gitea** webhook.
+2. Set **Target URL** to your Flipt webhook endpoint.
+3. Select `POST` and the `application/json` content type.
+4. Set **Secret** to your webhook secret.
+5. 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](https://docs.gitea.com/usage/webhooks) for details.
+
+</Tab>
+<Tab title="Bitbucket">
+
+For Bitbucket Cloud:
+
+1. Open your repository's settings and select **Webhooks > Add webhook**.
+2. Enter a title and set **URL** to your Flipt webhook endpoint.
+3. Set **Secret** to your webhook secret.
+4. 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](https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/) for details.
+
+</Tab>
+<Tab title="Azure DevOps">
+
+1. Open **Project settings > Service hooks** and create a subscription.
+2. Select **Web Hooks** as the service.
+3. Select **Code pushed** as the trigger and choose your repository.
+4. If you filter branches, include the branches that Flipt tracks.
+5. Set **URL** to your Flipt webhook endpoint.
+6. Configure Basic authentication with a username, such as `flipt`, and your webhook secret as the password.
+7. 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](https://learn.microsoft.com/en-us/azure/devops/service-hooks/services/webhooks?view=azure-devops) for details.
+
+</Tab>
+</Tabs>
+
+## 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.
+
+<Note>
+  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.
+</Note>
+
+## 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](/v2/webhooks/overview#monitoring) 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](/v2/webhooks/overview).

docs/v2/pro.mdx

@@ -43,6 +43,7 @@ mode: "wide"
 Flipt Pro provides native integration with popular source control management (SCM) platforms:
 
 - **Multi-Provider SCM Support**: Create merge proposals directly from the Flipt UI that generate pull requests across GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea
+- **Incoming Webhooks**: [Sync changes from Git](/v2/webhooks/overview) after a push or merge without waiting for the next poll
 - **GPG Commit Signing**: All commits are cryptographically signed for maximum security and auditability
 
 ### Integrated Secrets Management