Overview of steps

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

Set up webhooks for Discord

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


Update Mage project settings

Once you’ve set up webhooks for Discord, you should have a webhook URL that Discord provides.

Here is an example webhook (yours may vary):

https://discordapp.com/api/webhooks/XXX3514XXXXX/MHhahaduwa183-ccgfxcgv88kladJkjBJKB78CHCfds

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 SLA is missed.
      • In this context, SLA (Service Level Agreement) is an expected amount of time for the pipeline to complete.
      • If the pipeline runs longer than the SLA, an alert will be sent.
  5. In the metadata.yaml file, add the following values:

    notification_config:
      alert_on:
        ...
      discord_config:
        webhook_url: ...
    

    Change the webhook_url value to be the webhook URL you created from Discord.

Customize message templates

You can customize message templates in notification_config. Here is an example config:

notification_config:
  alert_on:
    ...
  discord_config:
    ...
  message_templates:
    failure:
      title: 'Failed to execute pipeline {pipeline_uuid} at {execution_time}'
      summary: >
        Failed to execute pipeline {pipeline_run_url}.
        Pipeline uuid: {pipeline_uuid}. Trigger name: {pipeline_schedule_name}.
        Test custom message.
    success:
      title: ...
      summary: ...
    passed_sla:
      title: ...
      summary: ...

You can customize the message template for success, failure, passed_sla scenarios. For each message template, you can specify the sentence on summary and the title.

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

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.


What next?

Whenever a pipeline run is successfully completed or fails, a Discord Channel message will appear in the channel you configured the webhook URL for.

Here is an example of what that message could look like: