> ## 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.

# Custom Monitoring

> Monitor your own websites and APIs with custom health checks

## Overview

Custom monitoring allows you to track the health and performance of your own websites, APIs, and custom endpoints that aren't available as pre-configured Sources in StatusStack.

***

## What Can You Monitor?

<CardGroup cols={2}>
  <Card title="Public Websites" icon="globe">
    Monitor your company website, landing pages, blogs, and documentation sites
  </Card>

  <Card title="API Endpoints" icon="code">
    Track REST APIs, GraphQL endpoints, and microservices with custom health checks
  </Card>

  <Card title="Private Services" icon="lock">
    Monitor authenticated endpoints with custom headers and authentication
  </Card>

  <Card title="SSL Certificates" icon="shield-check">
    Track certificate expiry dates and get alerts before they expire
  </Card>
</CardGroup>

***

## Creating Your First Monitor

<Steps>
  <Step title="Navigate to Website Monitors">
    In your dashboard, go to **Monitoring** → **Website Monitors**
  </Step>

  <Step title="Click Create Monitor">
    Click the **"Create Monitor"** button in the top-right
  </Step>

  <Step title="Configure Basic Settings">
    Enter monitor details:

    ```yaml theme={null}
    Name: Production API Health
    URL: https://api.yoursite.com/health
    Description: Monitors production API availability
    ```
  </Step>

  <Step title="Set Check Interval">
    Choose how often to check:

    * **30 seconds** - Critical production services
    * **60 seconds** - Standard production monitoring
    * **5 minutes** - Less critical endpoints
    * **15 minutes** - Internal tools and dashboards
  </Step>

  <Step title="Configure Validation">
    Define what "healthy" means:

    ```yaml theme={null}
    Expected Status Code: 200
    Timeout: 10 seconds
    Failure Threshold: 3 consecutive failures
    ```
  </Step>

  <Step title="Add to Stack">
    Select which Stack(s) to add this monitor to
  </Step>

  <Step title="Create Monitor">
    Click **"Create"** to start monitoring
  </Step>
</Steps>

<Note>
  Monitoring begins immediately after creation. First check results appear within your configured interval.
</Note>

***

## Monitor Configuration

### Basic Settings

| Field           | Description                       | Example                          |
| --------------- | --------------------------------- | -------------------------------- |
| **Name**        | Display name for the monitor      | "Production API"                 |
| **URL**         | Full URL to monitor               | `https://api.example.com/health` |
| **Description** | Optional notes about this monitor | "Main API health endpoint"       |
| **Team**        | Which team owns this monitor      | "Engineering Team"               |

### Check Configuration

<AccordionGroup>
  <Accordion title="Check Interval">
    How often StatusStack pings your endpoint:

    | Interval       | Use Case                       | Plan                |
    | -------------- | ------------------------------ | ------------------- |
    | **30 seconds** | Critical production services   | Pro/Enterprise      |
    | **60 seconds** | Standard production monitoring | Pro/Enterprise      |
    | **5 minutes**  | Less critical endpoints        | Free/Pro/Enterprise |
    | **15 minutes** | Internal tools, staging        | Free/Pro/Enterprise |
    | **30 minutes** | Development environments       | Free/Pro/Enterprise |
    | **60 minutes** | Low-priority monitoring        | Free/Pro/Enterprise |

    **Recommendation**: Start with 5 minutes, adjust based on criticality.
  </Accordion>

  <Accordion title="Timeout Duration">
    Maximum time to wait for a response:

    | Timeout        | Use Case                             |
    | -------------- | ------------------------------------ |
    | **5 seconds**  | Fast APIs, microservices             |
    | **10 seconds** | Standard APIs (recommended)          |
    | **15 seconds** | Slower APIs, complex pages           |
    | **30 seconds** | Very slow endpoints, data processing |

    **Tip**: If your endpoint occasionally takes > 10s, increase timeout to avoid false positives.
  </Accordion>

  <Accordion title="Failure Threshold">
    How many consecutive failures before alerting:

    | Threshold      | Behavior                           | Use Case                |
    | -------------- | ---------------------------------- | ----------------------- |
    | **1 failure**  | Alert immediately                  | Ultra-critical services |
    | **3 failures** | Alert after 3 checks (recommended) | Standard monitoring     |
    | **5 failures** | Alert after 5 checks               | Reduce false positives  |

    **Recommended**: 3 failures balances speed and accuracy.
  </Accordion>

  <Accordion title="Request Method">
    HTTP method to use:

    * **GET** (default) - Most health checks
    * **POST** - Endpoints requiring POST
    * **HEAD** - Just check if endpoint exists
    * **PUT** - Specific API operations
    * **OPTIONS** - CORS pre-flight checks

    **Most common**: GET for 99% of health checks.
  </Accordion>
</AccordionGroup>

### Advanced Configuration

<AccordionGroup>
  <Accordion title="Custom Headers">
    Add authentication or custom headers to your requests:

    ```yaml theme={null}
    Headers:
      Authorization: Bearer your-api-key-here
      X-API-Key: sk_live_abc123
      User-Agent: StatusStack Monitor
      Content-Type: application/json
    ```

    **Common use cases:**

    * API authentication
    * Custom API keys
    * User-Agent identification
    * Content negotiation
  </Accordion>

  <Accordion title="Expected Status Codes">
    Define which HTTP status codes mean "healthy":

    ```yaml theme={null}
    Expected Status Codes:
      - 200 (OK)
      - 201 (Created)
      - 204 (No Content)
      - 304 (Not Modified)
    ```

    **Default**: Only 200 is considered healthy.

    **When to customize**:

    * APIs returning 201 on success
    * Endpoints that return 204 No Content
    * Cached responses returning 304
  </Accordion>

  <Accordion title="Response Body Validation">
    Check if response contains specific text or JSON:

    **Text contains:**

    ```yaml theme={null}
    Response must contain: "healthy"
    ```

    **JSON validation:**

    ```yaml theme={null}
    Response must contain:
      status: "ok"
      uptime: > 0
    ```

    **Use for:**

    * Verify health check response format
    * Ensure critical data is present
    * Validate API contract
  </Accordion>

  <Accordion title="Follow Redirects">
    Choose whether to follow HTTP redirects:

    * **Enabled** (default): Follow 301/302 redirects
    * **Disabled**: Treat redirects as failures

    **Enable when:**

    * Monitoring root domains that redirect to www
    * Following HTTPS upgrades
    * Handling authentication redirects

    **Disable when:**

    * Redirects indicate a problem
    * You want to catch redirect loops
    * Testing specific endpoint behavior
  </Accordion>

  <Accordion title="SSL/TLS Verification">
    Configure SSL certificate checking:

    ```yaml theme={null}
    Verify SSL Certificate: Yes (default)
    Alert Days Before Expiry: 30 days
    ```

    **SSL monitoring includes:**

    * Certificate validity
    * Expiration date tracking
    * Chain verification
    * Hostname matching

    **Alerts sent when:**

    * Certificate expires in \< 30 days (warning)
    * Certificate expires in \< 7 days (critical)
    * Certificate is invalid or expired
  </Accordion>
</AccordionGroup>

***

## Common Use Cases

### Example 1: Simple Website Monitoring

Monitor a public website for uptime:

```yaml theme={null}
Monitor Configuration:
  Name: Company Website
  URL: https://www.yourcompany.com
  Method: GET
  Check Interval: 5 minutes
  Timeout: 15 seconds
  Expected Status: 200
  Failure Threshold: 3
  Verify SSL: Yes
  SSL Alert Threshold: 30 days
```

**What this monitors:**

* Website is reachable
* Returns 200 OK status
* Responds within 15 seconds
* SSL certificate is valid
* Certificate not expiring soon

### Example 2: API Health Check with Authentication

Monitor an authenticated API endpoint:

```yaml theme={null}
Monitor Configuration:
  Name: Production API Health
  URL: https://api.yourservice.com/health
  Method: GET
  Headers:
    Authorization: Bearer sk_live_abc123xyz
    Accept: application/json
  Check Interval: 60 seconds
  Timeout: 10 seconds
  Expected Status: 200
  Expected Body Contains: '"status":"healthy"'
  Failure Threshold: 3
```

**What this monitors:**

* API is responding
* Authentication working
* Health endpoint returns correct JSON
* Response time under 10 seconds

### Example 3: Database Connectivity Check

Monitor database connectivity through a health endpoint:

```yaml theme={null}
Monitor Configuration:
  Name: Database Health Check
  URL: https://api.yourservice.com/health/db
  Method: GET
  Headers:
    X-Health-Check-Token: secret-token-here
  Check Interval: 60 seconds
  Timeout: 5 seconds
  Expected Status: 200
  Expected Body Contains: '"db":"connected"'
  Failure Threshold: 2
```

**What this monitors:**

* Database connection pool healthy
* Queries executing successfully
* Connection not timing out

### Example 4: Webhook Endpoint Monitoring

Ensure your webhook endpoint is reachable:

```yaml theme={null}
Monitor Configuration:
  Name: Stripe Webhook Endpoint
  URL: https://api.yourservice.com/webhooks/stripe
  Method: POST
  Headers:
    Content-Type: application/json
    Stripe-Signature: test-signature
  Body: |
    {
      "type": "ping",
      "test": true
    }
  Check Interval: 5 minutes
  Timeout: 10 seconds
  Expected Status: 200
  Failure Threshold: 3
```

**What this monitors:**

* Webhook endpoint is reachable
* Accepts POST requests
* Returns success status

### Example 5: Multi-Region API Monitoring (Enterprise)

Monitor the same API from multiple regions:

```yaml theme={null}
Monitor Configuration:
  Name: Global API Endpoint
  URL: https://api.global-service.com/health
  Regions:
    - US East (Virginia)
    - EU West (Ireland)
    - Asia Pacific (Singapore)
  Check Interval: 60 seconds
  Aggregate Strategy: Any region passing = Operational
```

**What this monitors:**

* Global availability
* Regional performance
* Geographic redundancy

***

## Monitor Status Indicators

Your monitors report one of four statuses:

<CardGroup cols={2}>
  <Card title="Operational" icon="circle-check" color="#10b981">
    **All checks passing**

    * Endpoint is responding
    * Status code is expected
    * Response within timeout
    * Body validation passing (if configured)
  </Card>

  <Card title="Degraded" icon="triangle-exclamation" color="#f59e0b">
    **Some failures, not critical yet**

    * 1-2 failures (below threshold)
    * Slow responses (near timeout)
    * Intermittent issues

    **Action**: Monitor closely, investigate if continues
  </Card>

  <Card title="Critical" icon="circle-xmark" color="#ef4444">
    **Failure threshold exceeded**

    * 3+ consecutive failures (default)
    * Endpoint unreachable
    * Timeout exceeded
    * Unexpected status code

    **Action**: Immediate investigation required
  </Card>

  <Card title="Maintenance" icon="wrench" color="#3b82f6">
    **Scheduled maintenance window**

    * Monitoring paused
    * No alerts sent
    * Status page shows "Maintenance"

    **Action**: None - expected downtime
  </Card>
</CardGroup>

***

## Monitoring Best Practices

<AccordionGroup>
  <Accordion title="Create Dedicated Health Endpoints">
    **Don't monitor your homepage**

    ❌ **Bad**: Monitor `https://yoursite.com/`

    * Slow to load
    * May cache errors
    * Doesn't verify backend health

    ✅ **Good**: Create `https://api.yoursite.com/health`

    * Fast, lightweight response
    * Checks database connectivity
    * Verifies critical dependencies
    * Returns structured JSON

    **Example health endpoint response:**

    ```json theme={null}
    {
      "status": "healthy",
      "timestamp": "2025-01-19T10:30:00Z",
      "checks": {
        "database": "connected",
        "cache": "connected",
        "external_api": "reachable"
      }
    }
    ```
  </Accordion>

  <Accordion title="Set Appropriate Timeouts">
    **Match timeout to endpoint speed**

    | Endpoint Type     | Recommended Timeout |
    | ----------------- | ------------------- |
    | Fast APIs (\< 1s) | 5 seconds           |
    | Standard APIs     | 10 seconds          |
    | Complex queries   | 15 seconds          |
    | Data processing   | 30 seconds          |

    **Too short**: False positives from legitimate slow responses
    **Too long**: Late detection of actual outages
  </Accordion>

  <Accordion title="Use Failure Thresholds Wisely">
    **Prevent false alarms**

    **Network blips are common:**

    * Single timeout: Probably network
    * 2-3 timeouts: Investigate
    * 5+ timeouts: Definitely down

    **Recommended configuration:**

    ```yaml theme={null}
    Failure Threshold: 3
    Check Interval: 60 seconds
    Detection Time: ~3 minutes
    ```

    This balances:

    * ✅ Fast detection (3 minutes)
    * ✅ Filters false positives
    * ✅ Reasonable alert frequency
  </Accordion>

  <Accordion title="Authenticate Health Checks">
    **Protect sensitive endpoints**

    **Option 1: API Key Header**

    ```yaml theme={null}
    Headers:
      X-Health-Check-Token: secret-token-here
    ```

    **Option 2: Bearer Token**

    ```yaml theme={null}
    Headers:
      Authorization: Bearer your-api-key
    ```

    **Option 3: Custom Header**

    ```yaml theme={null}
    Headers:
      X-StatusStack-Monitor: true
    ```

    Then whitelist StatusStack's IP addresses in your firewall.
  </Accordion>

  <Accordion title="Monitor From User Perspective">
    **Test what users experience**

    Instead of monitoring:

    * ❌ Internal load balancer IP
    * ❌ Direct server endpoints
    * ❌ localhost addresses

    Monitor:

    * ✅ Public domain names
    * ✅ CDN URLs
    * ✅ Load balancer endpoints
    * ✅ SSL/TLS terminated URLs

    **Why**: Catches DNS issues, SSL problems, CDN failures
  </Accordion>
</AccordionGroup>

***

## Maintenance Windows

Schedule downtime to prevent false alerts:

### One-Time Maintenance

<Steps>
  <Step title="Open Monitor Settings">
    Navigate to your monitor and click **"Schedule Maintenance"**
  </Step>

  <Step title="Select Date & Time">
    Choose start and end times:

    ```yaml theme={null}
    Start: January 25, 2025 at 2:00 AM UTC
    End: January 25, 2025 at 4:00 AM UTC
    ```
  </Step>

  <Step title="Add Reason">
    Explain the maintenance (shown on status page):

    ```
    "Database migration and server upgrades"
    ```
  </Step>

  <Step title="Save Maintenance">
    Monitor enters maintenance mode automatically at scheduled time
  </Step>
</Steps>

### Recurring Maintenance

For regular maintenance windows:

```yaml theme={null}
Recurring Maintenance:
  Frequency: Weekly
  Day: Sunday
  Time: 2:00 AM - 4:00 AM UTC
  Reason: "Scheduled weekly maintenance"
```

**Common use cases:**

* Weekly deployment windows
* Monthly server patching
* Quarterly infrastructure upgrades

***

## Monitor Analytics

Each monitor provides detailed performance data:

### Uptime Metrics

<CardGroup cols={2}>
  <Card title="Current Uptime">
    * Last 24 hours
    * Last 7 days
    * Last 30 days
    * Last 90 days
  </Card>

  <Card title="Incident Statistics">
    * Total incidents
    * Average duration
    * MTTR (Mean Time to Recovery)
    * Longest outage
  </Card>
</CardGroup>

### Response Time Tracking

* **Average response time** over time
* **Slowest responses** (P95, P99 percentiles)
* **Response time trends** (improving/degrading)
* **Geographic performance** (Enterprise)

### Check History

View detailed check results:

```
✅ Jan 19, 2025 10:30:00 - 200 OK (125ms)
✅ Jan 19, 2025 10:29:00 - 200 OK (118ms)
❌ Jan 19, 2025 10:28:00 - Timeout after 10s
✅ Jan 19, 2025 10:27:00 - 200 OK (132ms)
```

**Useful for:**

* Identifying patterns
* Diagnosing intermittent issues
* Performance regression analysis

***

## Notifications

Configure alerts for monitor status changes:

### Creating Monitor Alerts

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

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

  <Step title="Configure Trigger">
    Set when to alert:

    ```yaml theme={null}
    Triggers:
      - Monitor becomes Critical
      - Monitor becomes Degraded (optional)
      - Monitor recovers
      - SSL certificate expiring (< 30 days)
    ```
  </Step>

  <Step title="Select Monitors">
    Choose which monitors trigger this rule:

    * All monitors
    * Specific monitors only
    * Monitors in specific Stacks
  </Step>

  <Step title="Choose Channels">
    Select notification channels:

    * Slack
    * Discord
    * Email
    * Microsoft Teams
    * PagerDuty
    * SMS (Twilio)
  </Step>

  <Step title="Save Rule">
    Activate the notification rule
  </Step>
</Steps>

See [Notification Setup Guide](/guides/notification-setup) for detailed configuration.

***

## Troubleshooting

### Monitor Showing as Down but Site is Up

**Possible causes:**

1. **Firewall blocking StatusStack** - Whitelist our monitoring IPs
2. **Rate limiting** - Exclude monitor user-agent from rate limits
3. **Authentication required** - Add proper headers
4. **Timeout too short** - Increase timeout duration
5. **SSL certificate issues** - Verify certificate validity

**Solutions:**

1. Check if endpoint is publicly accessible
2. Verify expected status code is correct
3. Increase timeout if endpoint is slow
4. Add authentication headers if required
5. Check SSL certificate expiration

### False Positive Alerts

**Issue**: Getting alerts but service is actually up

**Solutions:**

1. Increase failure threshold (3 → 5)
2. Increase timeout duration
3. Verify expected status codes include all valid responses
4. Check for rate limiting
5. Review response body validation rules

### Monitor Not Creating Alerts

**Issue**: Monitor shows as down but no notifications sent

**Check:**

1. Notification rules are configured
2. Notification channels are working
3. Alert levels match (Critical vs Degraded)
4. Monitor is assigned to the right Stack
5. Notification rule includes this monitor

***

## Monitor Limits by Plan

| Plan           | Max Monitors | Min Interval | Regions      |
| -------------- | ------------ | ------------ | ------------ |
| **Free**       | 1            | 5 minutes    | 1            |
| **Pro**        | 25           | 30 seconds   | 1            |
| **Enterprise** | Unlimited    | 30 seconds   | Multi-region |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Notification Setup" icon="bell" href="/guides/notification-setup">
    Configure alerts for monitor failures
  </Card>

  <Card title="Adding to Stacks" icon="layer-group" href="/guides/adding-services">
    Integrate monitors with your Stacks
  </Card>

  <Card title="Monitor Concepts" icon="book" href="/concepts/monitors">
    Deep dive into monitor architecture
  </Card>

  <Card title="Status Pages" icon="browser" href="/guides/status-pages">
    Display monitors on public status pages
  </Card>
</CardGroup>