Teams

Overview of steps

  1. Set up webhooks for Teams
  2. Update Mage project settings

Set up webhooks for Teams

Follow these instructions on Teams to setup incoming webhooks for your workspace.

Update Mage project settings

Once you’ve set up webhooks for Teams, you should have a webhook URL that Teams provides. Here is an example webhook (yours may vary):
https://teams.webhook.office.com/webhookb2/B04XXXXGY67/IncomingWebhook/1UgUkao8pXXXXPmsuXXXX2lk
Follow these steps to add that webhook URL to your project settings:
  1. Open the Mage tool in your browser (e.g. http://localhost:6789/).
  2. Open a pipeline and start editing it (e.g. http://localhost:6789/pipelines/example_pipeline/edit).
  3. In your left sidebar in the file browser, scroll all the way down and click on a file named metadata.yaml.
  4. In the metadata.yaml file, add a section with the following configuration or update the existing notification_config section:
    notification_config:
      alert_on:
        - trigger_failure
        - trigger_passed_sla
    
    If you omit the alert_on section it will default to trigger_failure and trigger_passed_sla. Options:
    • trigger_failure: alert when a run of a trigger fails
    • trigger_success: alert when a run of a trigger succeeds
    • trigger_passed_sla: alert when a run of a trigger passes sla
  5. In the metadata.yaml file, add the following values:
    notification_config:
      alert_on:
        ...
      teams_config:
        webhook_url:
          - 'https://teams.webhook.office.com/webhookb2/B04XXXXGY67/IncomingWebhook/1UgUkao8pXXXXPmsuXXXX2lk'
          - 'https://teams.webhook.office.com/webhookb2/B04XXXXGY67/IncomingWebhook/1UgUkao8pXXXXPmsuXXXX2lx'
    
    Change the webhook_url values to be the webhook URLs you created from Teams. The webhook_url must be a string if you are using version 0.9.73 or older and it only accepts one endpoint.
    teams_config:
        webhook_url: 'https://teams.webhook.office.com/webhookb2/B04XXXXGY67/IncomingWebhook/1UgUkao8pXXXXPmsuXXXX2lk'
    

Customize message templates

You can customize message templates in notification_config. Here is an example config:
notification_config:
  alert_on:
    ...
  teams_config:
    ...
  message_templates:
    failure:
      details: >
        Failed to execute pipeline {pipeline_run_url}.
        Pipeline uuid: {pipeline_uuid}. Trigger name: {pipeline_schedule_name}.
        Test custom message.
    success:
      details: ...
    passed_sla:
      details: ...
You can customize the message template for success, failure, passed_sla scenarios. For each message template, you can specify either summary or details.
  • If you specify the summary, the Teams message will be your summary + the url of the pipeline run page
  • If you specify the details, the details will be used as your Teams message directly
To interpolate variables in the message template, you can use {variable_name} syntax. Here are the supported variables:
  1. execution_time
  2. pipeline_run_url
  3. pipeline_schedule_id
  4. pipeline_schedule_name
  5. pipeline_schedule_description
  6. pipeline_uuid
  7. error
    • available only for the failure message template
  8. stacktrace
    • available only for the failure message template
Note: For pipeline_run_url, the default host is http://localhost:6789. You can specify MAGE_PUBLIC_HOST to be the host url you want to use in the notification messages.

🚀 Pro Only: Interpolate Mage Variables in Message Templates

If you’re using Mage Pro, you can interpolate environment variables and other Mage variables directly in your Teams message templates using the familiar Jinja-like syntax:
notification_config:
  message_templates:
    failure:
      details: >
        Failed at {{ env_var('ENVIRONMENT') }} environment.
        Pipeline run: {pipeline_run_url}.
In addition to the variables mentioned above (e.g. execution_time, pipeline_uuid, etc), you can also use the following in your message templates in Mage Pro:
  1. start_time
  2. end_time
  3. duration (in seconds)
  4. env (this gets the value stored in the ENV environment variable)
This makes your Teams notifications more dynamic and context-aware — ideal for multi-environment deployments and advanced workflows.

What next?

Whenever a pipeline run is successfully completed or fails, a Teams message will appear in the channel you configured the webhook URL for. Here is an example of what that message could look like:
Teams