Skip to content

Slack Notifications

This guide walks you through setting up Slack as your ArgoCD notification service.

Prerequisites

  • ArgoCD is installed on your cluster (typically with enable_argocd: "true" in your cluster definition)
  • External Secrets Operator is installed (typically with enable_external_secrets: "true")
  • You have a Slack workspace where you can create webhooks
  • You have permissions to store secrets in your cloud provider's secrets manager

Step 1: Create a Slack Webhook

In Your Slack Workspace

  1. Go to api.slack.com/apps
  2. Click "Create New App" → "From scratch"
  3. Name your app (e.g., "ArgoCD Notifications")
  4. Select your workspace and click "Create App"
  5. Go to "Incoming Webhooks" in the left sidebar
  6. Toggle "Activate Incoming Webhooks" to "On"
  7. Click "Add New Webhook to Workspace"
  8. Select the channel where ArgoCD should post notifications (e.g., #argocd-notifications)
  9. Click "Allow"
  10. Copy the webhook URL (looks like: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX)

Important: Keep this webhook URL secret. Anyone with this URL can post messages to your Slack channel.

Step 2: Store Webhook URL in Secrets Manager

Store the webhook URL in your cloud provider's secrets manager following the global secrets path.

AWS Secrets Manager

# Create the secret with the webhook URL
# Format: /CLUSTER_NAME/global/argocd-slack-webhook
aws secretsmanager create-secret \
  --name /my-cluster/global/argocd-slack-webhook \
  --secret-string '{"webhook-url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX"}'

Alternatively, use the AWS Console:

  1. Go to AWS Secrets Manager
  2. Click "Store a new secret"
  3. Choose "Other type of secret"
  4. Configure as follows:
  5. Key/value pairs:
    • Key: webhook-url
    • Value: (paste your webhook URL)
  6. Click "Next"
  7. Secret name: /my-cluster/global/argocd-slack-webhook
  8. Click "Store"

Azure Key Vault

# Create the secret in Azure Key Vault
az keyvault secret set \
  --vault-name my-keyvault \
  --name my-cluster-global-argocd-slack-webhook \
  --value '{"webhook-url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX"}'

Step 3: Enable ArgoCD Notifications in Your Cluster Definition

Edit your cluster definition in your tenant repository:

# clusters/my-cluster.yaml
apiVersion: v1
kind: Cluster
metadata:
  name: my-cluster
  labels:
    enable_argocd: "true"
    enable_external_secrets: "true"
    enable_argocd_notifications: "true"  # Enable notifications
  annotations:
    # Secret path to the Slack webhook URL in Secrets Manager
    argocd_notifications_secret_name: "my-cluster/global/argocd-slack-webhook"
spec:
  # ... rest of cluster definition

Step 4: Configure Slack Service in Tenant Repository

Create notification configuration in your tenant repository:

# config/argocd_notifications/all.yaml
externalSecret:
  secretName: "my-cluster/global/argocd-slack-webhook"
  key: "webhook-url"
  namespace: argocd

notifications:
  enabled: true

  slack:
    serviceName: slack
    channel: "#argocd-notifications"  # Can be overridden per app
    username: "ArgoCD"
    iconEmoji: ":rocket:"

  triggers:
    - name: on-deployed
      enabled: true
      when: app.status.operationState.phase in ['Succeeded'] and app.status.operationState.finishedAt != ''
      oncePer: app.status.operationState.finishedAt
      template: app-deployed

    - name: on-health-degraded
      enabled: true
      when: app.status.health.status == 'Degraded'
      oncePer: app.status.health.status
      template: app-health-degraded

    - name: on-sync-failed
      enabled: true
      when: app.status.operationState.phase in ['Error', 'Failed']
      oncePer: app.status.operationState.finishedAt
      template: app-sync-failed

Cluster-Specific Overrides

For cluster-specific configuration, create:

# config/argocd_notifications/my-cluster.yaml
externalSecret:
  secretName: "my-cluster/global/argocd-slack-webhook"
  key: "webhook-url"

notifications:
  slack:
    channel: "#my-cluster-deployments"  # Different channel for this cluster

Step 5: Enable Notifications on Your Applications

Add annotations to your Application resources to subscribe to notification triggers:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
  annotations:
    # Subscribe to on-deployed trigger for the default channel
    notifications.argoproj.io/subscribe.on-deployed.slack: "true"

    # Subscribe to specific channels per trigger
    notifications.argoproj.io/subscribe.on-deployed.slack: "#deployments"
    notifications.argoproj.io/subscribe.on-sync-failed.slack: "#alerts"
    notifications.argoproj.io/subscribe.on-health-degraded.slack: "#alerts"
spec:
  # ... rest of application definition

Annotation format: notifications.argoproj.io/subscribe.<trigger>.<service>: "<channel>"

  • <trigger>: on-deployed, on-sync-failed, on-health-degraded, or custom trigger name
  • <service>: slack (for Slack service)
  • <channel>: Slack channel name or true to use default channel from config

Step 6: Commit and Sync

Commit your changes to your tenant repository. The platform will:

  1. Detect the enable_argocd_notifications: "true" label in your cluster definition
  2. Deploy the ArgoCD Notifications chart
  3. Create an ExternalSecret to fetch the webhook URL from Secrets Manager
  4. Create the ConfigMap with notification triggers and templates
  5. Configure ArgoCD to send notifications to Slack

Notification Examples

Successful Deployment Notification

✔ Application my-app deployment is healthy.
Application details: https://argocd.example.com/applications/my-app

Sync Status: Synced
Repository: https://github.com/my-org/my-repo

Health Degraded Notification

⚠️ Application my-app health status is Degraded
Application details: https://argocd.example.com/applications/my-app

Health Status: Degraded
Repository: https://github.com/my-org/my-repo

Sync Failed Notification

❌ Application my-app sync is Failed.
Application details: https://argocd.example.com/applications/my-app

Sync Status: Failed
Repository: https://github.com/my-org/my-repo

Troubleshooting

Notifications Not Sending

  1. Check the ExternalSecret is synced: 

    kubectl get externalsecret -n argocd
kubectl describe externalsecret argocd-notifications-secret -n argocd

  2. Verify the Secret was created: 

    kubectl get secret argocd-notifications-secret -n argocd
kubectl get secret argocd-notifications-secret -n argocd -o jsonpath='{.data.slack-token}' | base64 -d

  3. Check the ConfigMap: 

    kubectl get configmap argocd-notifications-cm -n argocd

  4. Review ArgoCD Notifications logs: 

    kubectl logs -n argocd -l app.kubernetes.io/name=argocd-notifications -f

  5. Verify Application annotations: 

    kubectl get application my-app -n argocd -o yaml

Invalid Webhook URL

If you see errors like "Invalid webhook URL" in ArgoCD Notifications logs:

  1. Verify the webhook URL in Secrets Manager is correct
  2. Ensure the secret path in argocd_notifications_secret_name annotation matches the stored secret
  3. Verify the key name in externalSecret.key matches the JSON key in the secret

Secret Not Syncing

If the ExternalSecret is not syncing:

  1. Verify External Secrets Operator is installed and running
  2. Check that the ClusterSecretStore is configured correctly
  3. Ensure IAM/RBAC permissions allow reading from your secrets manager
  4. Review External Secrets Operator logs: 
    kubectl logs -n external-secrets -l app.kubernetes.io/name=external-secrets -f

Customization

Custom Message Templates

Override the default message templates in your config/argocd_notifications/all.yaml:

notifications:
  templates:
    appDeployed: |
      🎉 Deployment Success!
      App: {{.app.metadata.name}}
      Status: {{.app.status.sync.status}}
      Details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}

Additional Triggers

Add custom triggers based on application state:

notifications:
  triggers:
    - name: on-sync-running
      enabled: true
      when: app.status.operationState.phase in ['Running']
      oncePer: app.metadata.name
      template: app-sync-running

Multiple Notification Services

The ArgoCD Notifications framework supports multiple services. Configure additional services in your config/argocd_notifications/all.yaml.

See ArgoCD Notifications Services Documentation for all available services.

Reference