> ## Documentation Index
> Fetch the complete documentation index at: https://docs.statusstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification Setup

> Configure multi-channel alerts for status changes in StatusStack

## Overview

StatusStack's notification system alerts you when service status changes through multiple channels: Slack, Discord, Microsoft Teams, Email, SMS, and custom webhooks.

***

## Notification Channels

<CardGroup cols={2}>
  <Card title="Slack" icon="slack">
    Post alerts to Slack channels with rich formatting and threading
  </Card>

  <Card title="Discord" icon="discord">
    Send notifications to Discord servers with embeds and mentions
  </Card>

  <Card title="Microsoft Teams" icon="microsoft">
    Deliver adaptive cards to Teams channels
  </Card>

  <Card title="Email" icon="envelope">
    Send HTML emails to individuals or distribution lists
  </Card>

  <Card title="SMS" icon="message">
    Text message alerts via Twilio for critical issues
  </Card>

  <Card title="Webhooks" icon="webhook">
    Custom integrations with any service supporting webhooks
  </Card>
</CardGroup>

***

## Creating Your First Notification Rule

<Steps>
  <Step title="Navigate to Notifications">
    Go to **Settings** → **Notifications** in the dashboard
  </Step>

  <Step title="Click Create Rule">
    Click **"Create Notification Rule"** button
  </Step>

  <Step title="Name Your Rule">
    Give it a descriptive name:

    ```
    "Production Critical Alerts"
    "Degraded Service Warnings"
    "Client: Acme Corp Notifications"
    ```
  </Step>

  <Step title="Configure Triggers">
    Select when to send notifications:

    <Tabs>
      <Tab title="Status Changes">
        Alert on status transitions:

        * ☑️ Component becomes Critical
        * ☑️ Component becomes Degraded
        * ☑️ Component recovers (returns to Operational)
        * ☐ Component enters Maintenance
      </Tab>

      <Tab title="Monitor Events">
        Alert on monitor failures:

        * ☑️ Monitor goes down
        * ☑️ Monitor degraded
        * ☑️ Monitor recovers
        * ☑️ SSL certificate expiring
      </Tab>

      <Tab title="Incident Updates">
        Alert on incident lifecycle:

        * ☑️ New incident created
        * ☐ Incident updated
        * ☑️ Incident resolved
      </Tab>
    </Tabs>
  </Step>

  <Step title="Select What to Monitor">
    Choose which resources trigger this rule:

    ```yaml theme={null}
    Monitor:
      - All Stacks (or specific Stacks)
      - All Components (or specific Components)
      - All Monitors (or specific Monitors)
    ```

    **Tip**: Start broad, refine later to reduce noise
  </Step>

  <Step title="Choose Notification Channels">
    Select where to send alerts:

    * **Slack** → #production-alerts channel
    * **Email** → [ops@company.com](mailto:ops@company.com)
    * **PagerDuty** → On-call team (for Critical only)
  </Step>

  <Step title="Set Alert Level Filter (Optional)">
    Only alert for certain severity levels:

    ```yaml theme={null}
    Alert Levels:
      ☑️ Critical (outages)
      ☑️ Degraded (performance issues)
      ☐ Info (informational updates)
    ```
  </Step>

  <Step title="Save and Activate">
    Click **"Create Rule"** to activate notifications
  </Step>
</Steps>

***

## Channel Setup Guides

### Slack Integration

<Steps>
  <Step title="Create Slack Webhook">
    In Slack:

    1. Go to your workspace settings
    2. Navigate to **Apps** → **Incoming Webhooks**
    3. Click **"Add to Slack"**
    4. Select the channel (e.g., #alerts)
    5. Copy the webhook URL
  </Step>

  <Step title="Add to StatusStack">
    In StatusStack notification rule:

    1. Select **Slack** as channel
    2. Paste webhook URL
    3. Customize display name (optional)
  </Step>

  <Step title="Test Integration">
    Click **"Send Test Notification"** to verify
  </Step>
</Steps>

**Example Slack Message:**

```
🔴 Production API is DOWN

Stack: Production Infrastructure
Component: Production API
Status: Critical → Degraded → Critical
Duration: 5 minutes

View Details: https://statusstack.com/stacks/prod
```

**Advanced Options:**

* **Thread alerts** - Group related alerts in threads
* **Mentions** - @channel or @here for critical alerts
* **Custom username** - Set display name for bot
* **Custom emoji** - Use custom status emojis

### Discord Integration

<Steps>
  <Step title="Create Discord Webhook">
    In Discord:

    1. Open server settings
    2. Go to **Integrations** → **Webhooks**
    3. Click **"New Webhook"**
    4. Name it "StatusStack"
    5. Select channel
    6. Copy webhook URL
  </Step>

  <Step title="Add to StatusStack">
    In notification rule:

    1. Select **Discord** as channel
    2. Paste webhook URL
    3. Configure embed color preferences
  </Step>

  <Step title="Test">
    Send a test notification
  </Step>
</Steps>

**Example Discord Embed:**

```
━━━━━━━━━━━━━━━━━━━━
🔴  CRITICAL ALERT
━━━━━━━━━━━━━━━━━━━━

Production API is experiencing an outage

Stack: Production Infrastructure
Status: Critical
Started: 5 minutes ago

[View Details →]
```

**Features:**

* Rich embeds with color coding
* Role mentions (@everyone, @here)
* Inline fields for structured data
* Clickable links to status pages

### Microsoft Teams Integration

<Steps>
  <Step title="Create Incoming Webhook">
    In Microsoft Teams:

    1. Open the channel where you want notifications
    2. Click **⋯** → **Connectors**
    3. Search for **"Incoming Webhook"**
    4. Click **Configure**
    5. Name it "StatusStack Alerts"
    6. Upload StatusStack logo (optional)
    7. Copy webhook URL
  </Step>

  <Step title="Configure in StatusStack">
    1. Select **Microsoft Teams** channel
    2. Paste webhook URL
    3. Choose card style
  </Step>

  <Step title="Test Integration">
    Send test notification
  </Step>
</Steps>

**Example Teams Card:**

```
╔═══════════════════════════════╗
║  🔴  PRODUCTION ALERT         ║
╠═══════════════════════════════╣
║                               ║
║  Production API - Critical    ║
║                               ║
║  Stack: Production            ║
║  Duration: 5 minutes          ║
║  Impact: High                 ║
║                               ║
║  [View Status] [Acknowledge]  ║
╚═══════════════════════════════╝
```

**Features:**

* Adaptive Cards with actions
* Color-coded by severity
* Inline buttons
* Formatted text with markdown

### Email Notifications

<Steps>
  <Step title="Add Email Addresses">
    In notification rule:

    1. Select **Email** channel
    2. Enter recipient email addresses (comma-separated)
    3. Set email subject template (optional)
  </Step>

  <Step title="Customize Template (Optional)">
    Customize email content:

    * Subject line format
    * Include/exclude components
    * Branding (logo, colors)
  </Step>

  <Step title="Test Email">
    Send test to verify delivery
  </Step>
</Steps>

**Email Recipients:**

```
Single: ops@company.com
Multiple: ops@company.com, dev@company.com, alerts@company.com
Distribution List: team-alerts@company.com
```

**Example Email:**

```
Subject: [CRITICAL] Production API is DOWN

StatusStack Alert
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 Production API has changed status to CRITICAL

Stack: Production Infrastructure
Previous Status: Operational
Current Status: Critical
Duration: 5 minutes
Detected: January 19, 2025 at 10:30 AM UTC

Impact:
- API requests failing
- User-facing services affected
- Payment processing impacted

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

View full details:
https://statusstack.com/stacks/production

View incident updates:
https://statusstack.com/incidents/12345
```

### SMS Alerts (Twilio)

<Steps>
  <Step title="Configure Twilio">
    In StatusStack settings:

    1. Go to **Settings** → **Integrations** → **Twilio**
    2. Enter Account SID
    3. Enter Auth Token
    4. Enter Twilio phone number
    5. Save configuration
  </Step>

  <Step title="Add SMS to Rule">
    In notification rule:

    1. Select **SMS** channel
    2. Enter phone numbers (with country code)
    3. Set character limit (160 recommended)
  </Step>

  <Step title="Test SMS">
    Send test message
  </Step>
</Steps>

**Phone Number Format:**

```
US: +1-555-123-4567
UK: +44-20-1234-5678
International: +[country-code]-[number]
```

**Example SMS:**

```
StatusStack Alert:
Production API is DOWN
Status: Critical
View: https://stst.co/p/abc123
```

<Warning>
  **SMS is charged per message** by Twilio. Use SMS only for critical alerts to control costs.

  **Recommended**: Critical alerts only, not for degraded or info.
</Warning>

### Webhook Integration

<Steps>
  <Step title="Create Webhook Endpoint">
    Set up an endpoint to receive webhooks:

    ```javascript theme={null}
    POST https://your-service.com/webhooks/statusstack

    Headers:
      Content-Type: application/json
      X-StatusStack-Signature: sha256_signature
    ```
  </Step>

  <Step title="Configure in StatusStack">
    1. Select **Webhook** channel
    2. Enter your webhook URL
    3. Add custom headers (optional)
    4. Select HTTP method (POST default)
  </Step>

  <Step title="Verify Signature">
    Validate webhook authenticity:

    ```javascript theme={null}
    const crypto = require('crypto');

    function verifyWebhook(payload, signature, secret) {
      const hmac = crypto.createHmac('sha256', secret);
      const digest = hmac.update(payload).digest('hex');
      return digest === signature;
    }
    ```
  </Step>
</Steps>

**Webhook Payload:**

```json theme={null}
{
  "event": "component.status_changed",
  "timestamp": "2025-01-19T10:30:00Z",
  "stack": {
    "id": "stack_abc123",
    "name": "Production Infrastructure",
    "slug": "production"
  },
  "component": {
    "id": "comp_xyz789",
    "name": "Production API",
    "previous_status": "operational",
    "current_status": "critical"
  },
  "incident": {
    "id": "inc_123",
    "created_at": "2025-01-19T10:30:00Z",
    "resolved_at": null
  }
}
```

**Common Webhook Integrations:**

* PagerDuty
* Datadog
* New Relic
* Custom monitoring dashboards
* Incident management systems

***

## Notification Rules Best Practices

<AccordionGroup>
  <Accordion title="Start Simple, Iterate">
    **Don't over-configure initially**

    **Week 1**: Single rule for critical alerts

    ```yaml theme={null}
    Rule: "Critical Production Alerts"
    Triggers: Component becomes Critical
    Stacks: Production only
    Channels: Slack #alerts
    ```

    **Week 2**: Add degraded warnings

    ```yaml theme={null}
    Rule: "Degraded Service Warnings"
    Triggers: Component becomes Degraded
    Stacks: Production only
    Channels: Slack #warnings
    ```

    **Week 3**: Separate channels by service type

    ```yaml theme={null}
    Rule: "Payment Processing Alerts"
    Components: Stripe, Payment API
    Channels: Slack #payments-alerts, PagerDuty
    ```
  </Accordion>

  <Accordion title="Use Alert Levels Wisely">
    **Match severity to response urgency**

    | Level        | Definition                              | Response          | Channels                     |
    | ------------ | --------------------------------------- | ----------------- | ---------------------------- |
    | **Critical** | Service down, users impacted            | Immediate         | Slack, Email, SMS, PagerDuty |
    | **Degraded** | Performance issues, some users affected | Within 30 minutes | Slack, Email                 |
    | **Info**     | Status changes, maintenance             | Awareness only    | Email, Dashboard             |

    **Example rule structure:**

    ```yaml theme={null}
    Critical Alerts:
      Channels: Slack, Email, PagerDuty, SMS
      Stack: Production only
      Triggers: Critical status

    Degraded Warnings:
      Channels: Slack, Email
      Stacks: Production, Staging
      Triggers: Degraded status

    Info Updates:
      Channels: Email (digest)
      Stacks: All
      Triggers: All status changes
    ```
  </Accordion>

  <Accordion title="Reduce Notification Fatigue">
    **Avoid alert overload**

    **Bad**: Alert on everything

    ```yaml theme={null}
    ❌ All status changes
    ❌ Every component in every Stack
    ❌ Info + Degraded + Critical
    ❌ 10+ channels per rule
    ```

    **Good**: Targeted, actionable alerts

    ```yaml theme={null}
    ✅ Critical production components only
    ✅ Specific Stacks (Production)
    ✅ Critical and Degraded only
    ✅ 2-3 channels maximum
    ```

    **Techniques:**

    * **Rate limiting** - Max 1 alert per 15 minutes per component
    * **Deduplication** - Group related alerts
    * **Smart grouping** - "3 components down" instead of 3 separate alerts
    * **Escalation** - Start with Slack, escalate to SMS if unacknowledged
  </Accordion>

  <Accordion title="Separate Production from Non-Production">
    **Different urgency levels**

    ```yaml theme={null}
    Production Alerts:
      Stacks: Production Infrastructure
      Channels: Slack #prod-alerts, PagerDuty, SMS
      Triggers: Critical, Degraded
      Priority: High

    Staging Alerts:
      Stacks: Staging Environment
      Channels: Slack #staging-alerts
      Triggers: Critical only
      Priority: Medium

    Development Alerts:
      Stacks: Development
      Channels: Email digest
      Triggers: Critical only
      Priority: Low
    ```
  </Accordion>

  <Accordion title="Test Notification Rules">
    **Verify before you need them**

    **Monthly testing:**

    1. Send test notifications to all channels
    2. Verify delivery times
    3. Check formatting and content
    4. Ensure contact info is current
    5. Update on-call rotations

    **Use test button:**

    * Every notification rule has a "Test" button
    * Sends a sample alert to all configured channels
    * Verifies connectivity without triggering actual alerts
  </Accordion>
</AccordionGroup>

***

## Advanced Notification Features

### Notification Schedules

Send alerts only during specific times:

```yaml theme={null}
Notification Schedule:
  Active Hours: 9 AM - 5 PM EST (business hours)
  Active Days: Monday - Friday
  Holidays: Pause on US Federal Holidays
  Override: Allow Critical alerts 24/7
```

**Use cases:**

* Reduce after-hours noise for non-critical alerts
* Respect team working hours
* Pause during holidays

### Alert Escalation

Escalate to more urgent channels if unacknowledged:

```yaml theme={null}
Escalation Policy:
  Step 1: Slack #alerts (immediate)
  Step 2: Email on-call team (after 5 minutes)
  Step 3: SMS on-call engineer (after 15 minutes)
  Step 4: Call backup engineer (after 30 minutes)
```

**Enterprise feature**: Requires acknowledgment tracking

### Alert Grouping

Group related alerts to reduce spam:

```yaml theme={null}
Grouping Strategy:
  Group By: Stack
  Time Window: 5 minutes
  Result: "3 components in Production Stack are down"
  Instead of: 3 separate alert messages
```

### Custom Alert Templates

Customize notification content (Enterprise):

```handlebars theme={null}
{{status_emoji}} **{{component.name}}** is {{status}}

Stack: {{stack.name}}
Previous: {{previous_status}}
Current: {{current_status}}
Duration: {{duration}}

{{#if incident}}
Incident: {{incident.title}}
Updates: {{incident.updates_count}}
{{/if}}

View: {{stack.url}}
```

***

## Notification Limits by Plan

| Plan           | Max Rules | Channels per Rule | SMS Alerts    |
| -------------- | --------- | ----------------- | ------------- |
| **Free**       | 3         | 2                 | Not available |
| **Pro**        | 25        | Unlimited         | 100/month     |
| **Enterprise** | Unlimited | Unlimited         | Custom        |

***

## Troubleshooting

### Not Receiving Notifications

**Check:**

1. ✅ Notification rule is active (not paused)
2. ✅ Triggers are configured correctly
3. ✅ Stack/Component is included in rule
4. ✅ Alert level matches (Critical vs Degraded)
5. ✅ Notification channels are working

**Solutions:**

* Send test notification
* Check channel configuration
* Verify webhook URLs are accessible
* Check spam folder for emails
* Verify phone numbers for SMS

### Receiving Too Many Alerts

**Solutions:**

1. Increase failure thresholds on monitors
2. Add rate limiting to notification rules
3. Use alert grouping
4. Filter by alert level (Critical only)
5. Separate production from non-production

### Delayed Notifications

**Possible causes:**

1. Email server delays
2. Slack/Discord rate limiting
3. Webhook endpoint slow
4. StatusStack processing queue backlog

**Solutions:**

* Check channel-specific delivery times
* Reduce number of channels
* Optimize webhook endpoints
* Contact support if persistent

### Duplicate Notifications

**Causes:**

* Multiple rules matching same event
* Component in multiple Stacks with separate rules

**Solutions:**

* Review rule conditions
* Use more specific Stack/Component filters
* Enable deduplication (Enterprise)

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Slack Integration" icon="slack" href="/integrations/slack">
    Detailed Slack setup and customization
  </Card>

  <Card title="Discord Integration" icon="discord" href="/integrations/discord">
    Configure Discord webhooks and embeds
  </Card>

  <Card title="Webhook Integration" icon="code" href="/integrations/webhooks">
    Custom webhook integration guide
  </Card>

  <Card title="Notification Concepts" icon="bell" href="/concepts/notifications">
    Deep dive into notification architecture
  </Card>
</CardGroup>