Skip to main content

Custom Notification templates for Pipeline Notifications

note

Currently this feature is behind Feature Flag: PIPE_CUSTOM_NOTIFICATION_TEMPLATES However, since this is supported for centralised notification, we need PL_CENTRAL_NOTIFICATIONS and PIPE_CENTRALISED_NOTIFICATION to be enabled first. Please contact Harness support to enable this feature.

Users can create custom notification templates, allowing them to customise notification content and reuse templates within Centralised Pipeline Notifications. Templates support Pipeline Expressions and RBAC controls, ensuring flexibility and security.

This feature is especially useful when you want to:

  • Include specific information such as pipeline variables, stage outputs, or build inputs in the notification.
  • Send trimmed-down notifications that contain only the most relevant information.
  • Format notifications to align with internal standards or predefined payload structures.

This enhancement allows you to attach a Custom Notification Template to a notification rule and override the default message format with a custom webhook payload.

Custom templates give you control over the structure and content of the notification, support dynamic expressions (like pipeline and stage variables), and enable reuse across multiple pipelines.

We are going to discuss setting up a notification for Pipeline Events using Custom Notification Templates, at a certain scope.

You can set up custom notification template for Pipeline notification at following scope: Account, Organization and Project Level.

Setting Up Notifications Template​

note
  1. Custom Notification templates will work only for webhook notifications.
  2. Custom Notification templates support usage of template variables.
  3. Custom Notification templates will be an inline entity, meaning they cannot be stored in Git.
  4. All Pipeline and Stage-level variables are supported. If an expression cannot be resolved, it will return an empty string.
{
  "pipeline name": "pipeline",
  "stage name": "",
  "stage type": ""
}

In this example, we are going to discuss setting up custom notification template for Pipeline at Project Level:-

Attaching a Custom Notification Template to Pipeline Notifications​

Harness supports adding notification rules to pipelines. With this enhancement, you can now attach a Custom Notification Template to a pipeline notification rule to override the default message format and send custom webhook-based notifications.

This lets you replace the default notification message with a tailored structure defined in your template, including any runtime variables or expressions you've configured.

How to attach a template​

When configuring a pipeline-level notification rule, click on Notify in the right panel of the Pipeline Studio, and follow the existing flow until you reach the Notification Templates step:

  1. Under the Notification Templates tab:

    • Select your custom notification template.
    • If the template includes runtime variables, you’ll be prompted to provide values for those inputs.

info

Custom notification templates are supported only for webhook notification methods. Templates cannot be used with Email, Slack, Teams, or PagerDuty.

Once applied, the custom template overrides the default webhook payload sent during pipeline execution.

Variables in the Notification Template​

Notification templates support runtime inputs, which must be provided when configuring a notification rule—whether at the Centralised Notification Service (CNS) level or the pipeline level.

If a runtime variable is declared in the template, you will be prompted to enter values or expressions for it when selecting that template during notification rule configuration.

Use the following expression format to reference these variables in your template body: <+notification.variables.testVar>

You can also access the event type that triggered the notification using: <+notification.eventType>

Reconciliation of Notification Rules​

If you update a notification template by adding new runtime variables after it has already been attached to a notification rule, you may need to reconcile the rule to ensure those inputs are provided during execution.

Pipeline-level Notifications (via CNT tab)​

When a template used in a pipeline-level notification rule configured through the Notify (CNT) tab is updated, a warning message will appear when you attempt to run the pipeline:

  • "Entities referenced in this pipeline have been updated. Please reconcile and save the pipeline to run the latest version."

You can still proceed with the run, but any newly added variables will default to an empty string unless resolved.

To fully reconcile the rule with the latest version of the template, you need to reselect the template and provide values for the new inputs:

  1. Go to the Notify tab in the pipeline.
  2. Edit the notification rule.
  3. Navigate to the Templates tab.
  4. Reselect the same notification template.
  5. A prompt will appear asking you to enter values for the new runtime variables.

This updates the pipeline YAML to reference the latest template version and ensures all required inputs are captured.

Centralised Notifications (CNS)​

In Centralised Notification rules, no warning appears when you update a template. However, if a template has changes or new input variables, you can view all the impacted references in the Referenced By section of the template.

To fully reconcile the rule with the latest version of the template, you’ll still need to reselect the template and provide values for the new inputs.

Steps:

  1. Go to Notification Management under Project/Org/Account Settings.
  2. Edit the existing notification rule.
  3. In the Notification Templates step, reselect the same template.
  4. A prompt will appear for you to enter values for the newly added runtime variables.

This process ensures that all new inputs are captured and the rule remains valid.

By re-selecting the updated template in either case, you ensure your rule is aligned with the latest version and that all runtime inputs are explicitly provided.

YAML Structure​

Below is an example of the YAML structure for a Custom Notification Template where the type of the content body is set to YAML

template:
  name: sample_notification_template
  identifier: sample_notification_template
  versionLabel: v1
  type: Notification
  projectIdentifier: samples
  orgIdentifier: default
  tags: {}
  spec:
    body:
      content: |-
        {
            "pipeline name": "<+pipeline.name>",
            "description": "<+pipeline.description>",
            "eventType": "<+notification.eventType>",
            "runtime_var_1": "<+notification.variables.var1>"
        }
      type: YAML
    variables:
      - name: var1
        value: <+input>
        type: string

Pipeline YAML Using the Notification Template

You can reference this notification template from your pipeline YAML as follows:

notificationRules:
    - name: notify_demo
      identifier: notify_demo
      pipelineEvents:
        - type: PipelineStart
        - type: PipelineEnd
      notificationMethod:
        type: Webhook
        spec:
          webhookUrl: https://your/webhook/url
      enabled: true
      template:
        versionLabel: v1
        templateRef: sample_notification_template
        templateInputs:
          variables:
            - name: var1
              type: string
              value: test_val

Sample JSON Response​

Below is an example of the JSON response received when this notification is triggered:

CD Events Schema​

To align with the CDEvents standard, Harness has contributed several notification templates to the public CD Events schema repository based on our supported events.

You can explore these templates here:
CD Events Schema on GitHub

The public repository includes a brief explanation of the schema, structure, and supported event types. If you think anything is missing or requires further clarification, feel free to raise a GitHub issue or contact us.