Notifications

Configure email notifications for node downtime, backup events, storage issues, and disk space warnings.

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 API

curl -X POST http://localhost:8100/api/v1/notifications/providers \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMTP",
    "name": "Company Email",
    "config": {
      "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"
      ]
    },
    "isDefault": true,
    "notifyNodeDowntime": true,
    "notifyBackupSuccess": false,
    "notifyBackupFailure": true,
    "notifyS3ConnIssue": true,
    "notifyDiskSpaceWarning": true
  }'

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:

curl -X POST http://localhost:8100/api/v1/notifications/providers/1/test \
  -H "Content-Type: application/json" \
  -d '{
    "testEmail": "your-email@yourcompany.com"
  }'

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

curl -X PUT http://localhost:8100/api/v1/notifications/providers/1 \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMTP",
    "name": "Company Email",
    "config": { ... },
    "isDefault": true,
    "notifyNodeDowntime": true,
    "notifyBackupSuccess": true,
    "notifyBackupFailure": true,
    "notifyS3ConnIssue": true,
    "notifyDiskSpaceWarning": true
  }'

List Providers

curl http://localhost:8100/api/v1/notifications/providers | jq

Delete a Provider

curl -X DELETE http://localhost:8100/api/v1/notifications/providers/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

curl -X POST http://localhost:8100/api/v1/notifications/providers \
  -H "Content-Type: application/json" \
  -d '{
    "type": "WEBHOOK",
    "name": "PagerDuty Webhook",
    "config": {
      "url": "https://events.pagerduty.com/v2/enqueue",
      "format": "GENERIC",
      "secret": "hmac-signing-secret",
      "timeout": 30,
      "customHeaders": {
        "X-Custom-Header": "value"
      }
    },
    "isDefault": false,
    "notifyNodeDowntime": true,
    "notifyBackupFailure": true
  }'

Slack Webhook

curl -X POST http://localhost:8100/api/v1/notifications/providers \
  -H "Content-Type: application/json" \
  -d '{
    "type": "WEBHOOK",
    "name": "Ops Slack Channel",
    "config": {
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "format": "SLACK"
    },
    "isDefault": false,
    "notifyNodeDowntime": true,
    "notifyBackupFailure": true,
    "notifyBackupSuccess": true
  }'

Discord Webhook

curl -X POST http://localhost:8100/api/v1/notifications/providers \
  -H "Content-Type: application/json" \
  -d '{
    "type": "WEBHOOK",
    "name": "Alerts Discord",
    "config": {
      "url": "https://discord.com/api/webhooks/xxx/yyy",
      "format": "DISCORD"
    },
    "isDefault": false,
    "notifyNodeDowntime": true
  }'

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

Configure Monitoring for Prometheus-based alerting (complementary to email)
Backups to set up scheduled backups that trigger notifications
Terraform Provider to manage notifications as code

Notification Events​

Supported Providers​

Set Up Email Notifications​

Step 1: Create an SMTP Provider​

Via API​

Via Terraform​

Step 2: Test the Provider​

SMTP Configuration Reference​

Common SMTP Providers​

Manage Notification Preferences​

Update Which Events Trigger Notifications​

List Providers​

Delete a Provider​

Email Content​

Node Downtime​

Backup Failure​

Disk Space Warning​

Webhook Notifications (Pro)​

Generic Webhook​

Slack Webhook​

Discord Webhook​

Webhook Payload Format (Generic)​

Troubleshooting​

"Test email failed"​

Not receiving notifications​

Next Steps​