Configuring notifications

This page describes how to configure piped to send notifications to external services.

PipeCD events (deployment triggered, planned, completed, analysis result, piped started…) can be sent to external services like Slack or a Webhook service. While forwarding those events to a chat service helps developers have a quick and convenient way to know the deployment’s current status, forwarding to a Webhook service may be useful for triggering other related tasks like CI jobs.

PipeCD events are emitted and sent by the piped component. So all the needed configurations can be specified in the piped configuration file. Notification configuration including:

  • a list of Routes which used to match events and decide where the event should be sent to
  • a list of Receivers which used to know how to send events to the external service

Notification Route matches events based on their metadata like name, group, app, labels. Below is the list of supporting event names and their groups.

Event Group Supported Description
DEPLOYMENT_TRIGGERED DEPLOYMENT

DEPLOYMENT_PLANNED DEPLOYMENT

DEPLOYMENT_APPROVED DEPLOYMENT

DEPLOYMENT_WAIT_APPROVAL DEPLOYMENT

DEPLOYMENT_ROLLING_BACK DEPLOYMENT

PipeCD sends a notification when a deployment is completed, while it does not send a notification when a deployment status changes to DEPLOYMENT_ROLLING_BACK because it is not a completion status. See #4547
DEPLOYMENT_SUCCEEDED DEPLOYMENT

DEPLOYMENT_FAILED DEPLOYMENT

DEPLOYMENT_CANCELLED DEPLOYMENT

DEPLOYMENT_TRIGGER_FAILED DEPLOYMENT

APPLICATION_SYNCED APPLICATION_SYNC

APPLICATION_OUT_OF_SYNC APPLICATION_SYNC

APPLICATION_HEALTHY APPLICATION_HEALTH

APPLICATION_UNHEALTHY APPLICATION_HEALTH

PIPED_STARTED PIPED

PIPED_STOPPED PIPED

Sending notifications to Slack

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  notifications:
    routes:
      # Sending all event which contains labels `env: dev` to dev-slack-channel.
      - name: dev-slack
        labels:
          env: dev
        receiver: dev-slack-channel
      # Only sending deployment started and completed events which contains
      # labels `env: prod` and `team: pipecd` to prod-slack-channel.
      - name: prod-slack
        events:
          - DEPLOYMENT_TRIGGERED
          - DEPLOYMENT_SUCCEEDED
        labels:
          env: prod
          team: pipecd
        receiver: prod-slack-channel
      - name: integration-slack
        receiver: integration-slack-api
    receivers:
      - name: dev-slack-channel
        slack:
          hookURL: https://slack.com/dev
      - name: prod-slack-channel
        slack:
          hookURL: https://slack.com/prod
      - name: integration-slack-api
        slack:
          oauthToken: "token"
          channelID: "testid"

Deployment was triggered, planned and completed successfully

A piped has been started

For detailed configuration, please check the configuration reference for Notifications section.

Sending notifications to external services via webhook

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  notifications:
    routes:
      # Sending all events an external service.
      - name: all-events-to-a-external-service
        receiver: a-webhook-service
    receivers:
      - name: a-webhook-service
        webhook:
          url: {WEBHOOK_SERVICE_URL}
          signatureValue: {RANDOM_SIGNATURE_STRING}

For detailed configuration, please check the configuration reference for NotificationReceiverWebhook section.


Last modified January 17, 2024: Fix docs about notifications for DEPLOYMENT_ROLLING_BACK (#4751) (522a13b8)