ChainLaunch

Notifications

Core ChainLaunch supports basic email notifications. ChainLaunch Pro adds Slack/Teams/PagerDuty providers, custom templates, severity routing, and…

Pro extensions

Core ChainLaunch supports basic email notifications. ChainLaunch Pro adds Slack/Teams/PagerDuty providers, custom templates, severity routing, and integration with Webhooks. This page covers both.

Configure email notifications for node downtime, backup events, storage issues, and disk space warnings. For machine-to-machine integrations (signed HTTP callbacks), see Webhooks.

Secrets are protected

Provider secrets (SMTP password, webhook secret, API tokens, custom auth headers) are write-only: they are redacted as __REDACTED__ in API responses and encrypted at rest with the ChainLaunch master key. You never need to re-enter a secret when editing a provider. See Security Best Practices and Encryption at Rest.

Notification Events

Event Description When it fires
Node Downtime A node is unreachable or has stopped Node health check fails
Node Recovery A previously-down node is back online Node health check passes after downtime
Backup Success A scheduled backup completed After each successful backup
Backup Failure A scheduled backup failed When a backup errors out
S3 Connection Issue Cannot reach the backup S3 endpoint During backup target connectivity check
Disk Space Warning Disk usage exceeds threshold When disk usage crosses the warning threshold

Supported Providers

Provider Type Edition Configuration
SMTP Email Community + Pro SMTP server, credentials, recipients
Webhook HTTP POST Pro only URL, format (Generic/Slack/Discord), HMAC secret

Pro Feature

Webhook notifications (Slack, Discord, generic HTTP) require ChainLaunch Pro. The SMTP provider is available in both editions.

Set Up Email Notifications

Step 1: Create an SMTP Provider

Via CLI

Save the provider's config JSON to a file (smtp.json):

{
  "host": "smtp.gmail.com",
  "port": 587,
  "username": "chainlaunch-alerts@yourcompany.com",
  "password": "app-password-here",
  "from": "chainlaunch-alerts@yourcompany.com",
  "tls": true,
  "recipients": [
    "ops-team@yourcompany.com",
    "devops-lead@yourcompany.com"
  ]
}

Then create the provider:

chainlaunch notifications providers create \
  --type SMTP \
  --name "Company Email" \
  --config-file smtp.json \
  --default \
  --notify-node-downtime \
  --notify-backup-failure \
  --notify-s3-conn-issue \
  --notify-disk-space-warning

Via Terraform

resource "chainlaunch_notification_provider" "email" {
  type       = "SMTP"
  name       = "Company Email"
  is_default = true
 
  smtp_config = {
    host       = "smtp.gmail.com"
    port       = 587
    username   = "chainlaunch-alerts@yourcompany.com"
    password   = var.smtp_password
    from       = "chainlaunch-alerts@yourcompany.com"
    tls        = true
    recipients = ["ops-team@yourcompany.com"]
  }
 
  notify_node_downtime      = true
  notify_backup_success     = false
  notify_backup_failure     = true
  notify_s3_conn_issue      = true
  notify_disk_space_warning = true
}

Step 2: Test the Provider

Send a test email to verify your SMTP configuration:

chainlaunch notifications providers test 1

Response:

{
  "status": "success",
  "message": "Test email sent successfully",
  "testedAt": "2026-03-24T10:30:00Z"
}

SMTP Configuration Reference

Field Required Description Example
host Yes SMTP server hostname smtp.gmail.com
port Yes SMTP port (25, 465, 587) 587
username Yes SMTP login username alerts@company.com
password Yes SMTP login password or app password xxxx-xxxx-xxxx
from Yes Sender email address chainlaunch@company.com
tls No Enable TLS encryption true
recipients No List of recipient emails. If empty, sends to from address ["ops@company.com"]

Common SMTP Providers

Provider Host Port TLS Notes
Gmail smtp.gmail.com 587 Yes Requires app password
Outlook/O365 smtp.office365.com 587 Yes
Amazon SES email-smtp.us-east-1.amazonaws.com 587 Yes Requires SES credentials
SendGrid smtp.sendgrid.net 587 Yes Use API key as password
Mailgun smtp.mailgun.org 587 Yes
Self-hosted mail.yourcompany.com 25/587 Optional

Manage Notification Preferences

Update Which Events Trigger Notifications

chainlaunch notifications providers update 1 \
  --type SMTP --name "Company Email" --config-file smtp.json \
  --default \
  --notify-node-downtime \
  --notify-backup-success \
  --notify-backup-failure \
  --notify-s3-conn-issue \
  --notify-disk-space-warning

List Providers

chainlaunch notifications providers list

Delete a Provider

chainlaunch notifications providers delete 1

Email Content

Each notification type sends a formatted email with relevant details:

Node Downtime

Subject: [ChainLaunch] Node Down: peer0-org1

Node peer0-org1 (FABRIC_PEER) is unreachable.
Down since: 2026-03-24T10:15:00Z
Duration: 5 minutes
Error: connection refused

Dashboard: http://localhost:8100/nodes/1

Backup Failure

Subject: [ChainLaunch] Backup Failed: daily-s3-backup

Backup for schedule "daily-s3-backup" failed.
Target: production-s3 (S3)
Error: AccessDenied: bucket not accessible
Started: 2026-03-24T02:00:00Z
Duration: 12 seconds

Disk Space Warning

Subject: [ChainLaunch] Disk Space Warning

Disk usage on /var/lib/chainlaunch has reached 85%.
Used: 170 GB / 200 GB
Available: 30 GB
Threshold: 80%

Webhook Notifications (Pro)

ChainLaunch Pro supports webhook notifications with three formats:

Generic Webhook

Save the webhook config to pagerduty.json:

{
  "url": "https://events.pagerduty.com/v2/enqueue",
  "format": "GENERIC",
  "secret": "hmac-signing-secret",
  "timeout": 30,
  "customHeaders": { "X-Custom-Header": "value" }
}

Then create the provider:

chainlaunch notifications providers create \
  --type WEBHOOK --name "PagerDuty Webhook" \
  --config-file pagerduty.json \
  --notify-node-downtime --notify-backup-failure

Slack Webhook

slack.json:

{
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "format": "SLACK"
}
chainlaunch notifications providers create \
  --type WEBHOOK --name "Ops Slack Channel" \
  --config-file slack.json \
  --notify-node-downtime --notify-backup-failure --notify-backup-success

Discord Webhook

discord.json:

{
  "url": "https://discord.com/api/webhooks/xxx/yyy",
  "format": "DISCORD"
}
chainlaunch notifications providers create \
  --type WEBHOOK --name "Alerts Discord" \
  --config-file discord.json \
  --notify-node-downtime

Webhook Payload Format (Generic)

Generic webhooks receive a JSON payload:

{
  "eventId": "evt_abc123",
  "eventType": "NODE_DOWNTIME",
  "severity": "CRITICAL",
  "timestamp": "2026-03-24T10:15:00Z",
  "source": {
    "nodeId": "1",
    "instanceId": "cl-prod-01",
    "version": "0.5.0"
  },
  "data": {
    "nodeName": "peer0-org1",
    "nodeType": "FABRIC_PEER",
    "downSince": "2026-03-24T10:10:00Z",
    "error": "connection refused"
  }
}

When a secret is configured, the payload is signed with HMAC-SHA256. Verify the signature in the X-Signature-256 header.

Troubleshooting

"Test email failed"

  • Verify SMTP host and port are correct
  • Check username/password (Gmail requires app passwords, not account passwords)
  • Ensure TLS setting matches the port (587 = STARTTLS, 465 = implicit TLS)
  • Check firewall allows outbound SMTP traffic

Not receiving notifications

  • Verify the provider has the specific event types enabled (notifyNodeDowntime, etc.)
  • Check the provider's lastTestStatus field
  • Look at ChainLaunch logs for SMTP errors
  • Check spam/junk folder

Next Steps