MLflow Webhooks: Trigger CI/CD on Model Promotion (2026)

MLflow Webhooks let you automate your MLOps pipeline by triggering CI/CD workflows when specific events happen in MLflow, like a model being promoted to production.

Imagine you have a model registry in MLflow. You’ve trained a model, logged it, and now you’re ready to deploy it. Traditionally, this involves manual steps: someone notices the model is ready, triggers a CI/CD job, and then deploys it. MLflow Webhooks eliminate this manual handoff.

Here’s how it works in practice:

Let’s say you have a CI/CD pipeline set up with Jenkins, GitLab CI, or GitHub Actions. When you promote a model version to the "Production" stage in MLflow, an MLflow Webhook, configured to listen for this specific event, will send an HTTP POST request to a predefined URL. This URL is typically an endpoint in your CI/CD system that’s set up to listen for such events.

MLflow Configuration:

First, you need to enable webhooks in your MLflow tracking server. This is usually done by setting an environment variable or a configuration parameter when starting the MLflow server.

mlflow server \
  --host 0.0.0.0 \
  --port 5000 \
  --backend-store-uri sqlite:///mlflow.db \
  --default-artifact-root s3://my-mlflow-bucket/ \
  --serve-artifacts \
  --webhook-origins '*' # Or a specific origin like 'http://your-ci-cd-host:8080'

The --webhook-origins '*' allows requests from any origin. For production, you’d restrict this to your CI/CD server’s URL for security.

Creating a Webhook in MLflow:

You can create webhooks using the MLflow UI or the MLflow API.

Using the MLflow UI:

1. Navigate to your MLflow project.
2. Go to "Settings" or "Admin" (depending on MLflow version).
3. Find the "Webhooks" section.
4. Click "Add Webhook."
5. Event Type: Select "MODEL_VERSION_TRANSITIONED_STAGE." This is the event that fires when a model version’s stage changes (e.g., from "Staging" to "Production").
6. Webhook URL: Enter the URL of your CI/CD system’s webhook listener. For example, http://jenkins.yourcompany.com:8080/github-webhook/ or https://gitlab.com/api/v4/projects/123/hooks.
7. Secret (Optional but Recommended): Provide a secret token. Your CI/CD system will use this to verify that the webhook request actually came from MLflow.
8. Enable/Save: Save the webhook configuration.

CI/CD System Configuration (Example with GitHub Actions):

Your CI/CD pipeline needs to be able to receive and process the webhook. Here’s a conceptual example for GitHub Actions. You’d typically have a workflow file (.github/workflows/deploy.yml) that listens for an incoming webhook.

name: MLflow Model Deployment Trigger

on:
  repository_dispatch: # This event type can be triggered externally
    types: [model_promoted] # Custom event type we'll send from MLflow

jobs:
  deploy-model:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Get Model Information
        env:

          MLFLOW_WEBHOOK_SECRET: ${{ secrets.MLFLOW_WEBHOOK_SECRET }} # Your secret

        run: |
          # In a real scenario, you'd parse the incoming payload to get model details.
          # For this example, we'll assume the payload contains 'model_name' and 'model_version'.
          # If using github_dispatch, the payload is in github.event.client_payload

          MODEL_NAME=$(echo "${{ github.event.client_payload.model_name }}" | tr '[:upper:]' '[:lower:]') # GitHub Actions event payload


          MODEL_VERSION="${{ github.event.client_payload.model_version }}"

          echo "Deploying model: $MODEL_NAME version: $MODEL_VERSION"
          # You would then use these variables to trigger your deployment script
          # e.g., ./scripts/deploy.sh $MODEL_NAME $MODEL_VERSION

Triggering the Webhook from MLflow:

When you transition a model version in the MLflow UI:

1. Go to "Models" -> select your model -> select the specific model version.
2. Click "Transition Stage."
3. Choose "Production" and click "Transition."

This action in MLflow will trigger the webhook. The MLflow server will send an HTTP POST request to your specified URL. The payload of this request will contain details about the event, including the model name, model version, and the stage transition.

The Payload:

A typical payload for a MODEL_VERSION_TRANSITIONED_STAGE event looks like this JSON:

{
  "event": "MODEL_VERSION_TRANSITIONED_STAGE",
  "timestamp": 1678886400000,
  "model_name": "my-classification-model",
  "model_version": "3",
  "to_stage": "Production",
  "from_stage": "Staging",
  "user_id": "admin",
  "webhook_id": "a1b2c3d4-e5f6-7890-1234-abcdef123456"
}

Security Considerations:

• Secret Verification: Always use a secret. Your CI/CD system should verify the X-MLflow-Signature header (if provided by MLflow) or compare a custom header against your secret to ensure the request is legitimate.
• Webhook Origins: Restrict --webhook-origins to specific, trusted domains.
• HTTPS: Use HTTPS for your webhook URLs to encrypt traffic.

This setup automates the critical step of initiating a deployment when a model is deemed ready for production, bridging the gap between model management and automated deployment pipelines. The next logical step is to explore how to handle different event types, like model registration or deletion, to build even more sophisticated MLOps workflows.