Configure Flux Notification Controller for Alerts and Webhooks (2026)

Flux Notification Controller can be configured to send alerts and webhooks for various events.

Here’s how you can set it up to send alerts to Slack and trigger a webhook on commit changes:

Setting Up Slack Alerts

First, let’s configure Flux to send notifications to Slack.

1. Create a Slack App and Get an Incoming Webhook URL:

• Go to the Slack API website and create a new app.
• Enable "Incoming Webhooks" for your app.
• Add a new webhook to your workspace and choose the channel where you want to receive notifications.
• Copy the generated webhook URL. It will look something like https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX.

2. Create a Kubernetes Secret for the Webhook URL:

You need to store your Slack webhook URL securely in a Kubernetes Secret.

apiVersion: v1
kind: Secret
metadata:
  name: slack-credentials
  namespace: flux-system # Or the namespace where your notification controller is running
type: Opaque
stringData:
  address: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"

Apply this secret: kubectl apply -f slack-secret.yaml

3. Create a Notification Provider Resource:

This resource tells Flux how to connect to Slack.

apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Provider
metadata:
  name: slack
  namespace: flux-system
spec:
  type: slack
  channel: "#flux-alerts" # The channel name you configured in Slack
  secretRef:
    name: slack-credentials

Apply this provider: kubectl apply -f slack-provider.yaml

4. Create a Notification Controller Resource:

This is the core resource that defines what events trigger notifications and where they go.

apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Alert
metadata:
  name: flux-alerts
  namespace: flux-system
spec:
  eventSeverity: info # Can be "info", "warn", "error"
  providerRef:
    name: slack # References the Provider resource created above
  eventSources:
    - reconciler: kustomize # Or helm, source, etc.
      name: flux-system # The name of the reconciler resource you want to monitor
      namespace: flux-system

Apply this alert: kubectl apply -f flux-alert.yaml

Now, whenever a Kustomization in the flux-system namespace reconciles, you’ll get a notification in your Slack channel.

Triggering a Webhook on Commit Changes

Let’s say you want to trigger an external service (e.g., a CI/CD pipeline, a deployment script) whenever a new commit is detected in your Git repository.

1. Create a Notification Controller Resource for Webhook:

apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Webhook
metadata:
  name: git-commit-webhook
  namespace: flux-system
spec:
  # This is the URL of your external service that will receive the webhook.
  # Replace with your actual webhook endpoint.
  address: "http://your-external-webhook-service.example.com/flux-events"
  # The payload that will be sent. You can customize this.
  # ${commit} and ${author} are variables that Flux will substitute.
  payload: |
    {
      "type": "git-commit",
      "commit": "${commit}",
      "author": "${author}",
      "message": "${message}",
      "repository": "${repository}"
    }
  eventSeverity: info
  eventSources:
    - reconciler: source # Monitor the GitRepository source controller
      name: my-git-repo # The name of your GitRepository resource
      namespace: flux-system # The namespace of your GitRepository resource

Apply this webhook: kubectl apply -f git-commit-webhook.yaml

Now, when your GitRepository resource named my-git-repo in the flux-system namespace detects a new commit, Flux will send a POST request to http://your-external-webhook-service.example.com/flux-events with the specified payload.

Key Concepts and Customization:

• eventSeverity: You can filter notifications based on severity. Common values are info, warn, and error.
• eventSources: This array allows you to specify which Flux controllers and resources should trigger notifications. You can monitor kustomize, helm, source, etc.
• reconciler: The type of Flux controller to monitor (e.g., kustomize, helm, source).
• name and namespace: The specific resource within the reconciler you want to watch.
• Payload Variables: For webhooks, you can use variables like ${commit}, ${author}, ${message}, ${repository}, ${timestamp}, ${url} to customize the data sent.

The Notification Controller is a powerful tool for integrating Flux with your existing alerting and automation workflows. By defining Provider, Alert, and Webhook resources, you can create a robust notification system tailored to your needs.