Custom Monitoring - StatusStack Documentation

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?

Public Websites

Monitor your company website, landing pages, blogs, and documentation sites

API Endpoints

Track REST APIs, GraphQL endpoints, and microservices with custom health checks

Private Services

Monitor authenticated endpoints with custom headers and authentication

SSL Certificates

Track certificate expiry dates and get alerts before they expire

Creating Your First Monitor

Navigate to Website Monitors

In your dashboard, go to Monitoring → Website Monitors

Click Create Monitor

Click the “Create Monitor” button in the top-right

Configure Basic Settings

Enter monitor details:

Name: Production API Health
URL: https://api.yoursite.com/health
Description: Monitors production API availability

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

Configure Validation

Define what “healthy” means:

Expected Status Code: 200
Timeout: 10 seconds
Failure Threshold: 3 consecutive failures

Add to Stack

Select which Stack(s) to add this monitor to

Create Monitor

Click “Create” to start monitoring

Monitoring begins immediately after creation. First check results appear within your configured interval.

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

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.

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.

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.

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.

Advanced Configuration

Custom Headers

Add authentication or custom headers to your requests:

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

Expected Status Codes

Define which HTTP status codes mean “healthy”:

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

Response Body Validation

Check if response contains specific text or JSON:Text contains:

Response must contain: "healthy"

JSON validation:

Response must contain:
  status: "ok"
  uptime: > 0

Use for:

Verify health check response format
Ensure critical data is present
Validate API contract

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

SSL/TLS Verification

Configure SSL certificate checking:

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

Common Use Cases

Example 1: Simple Website Monitoring

Monitor a public website for uptime:

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:

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:

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:

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:

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:

Operational

All checks passing

Endpoint is responding
Status code is expected
Response within timeout
Body validation passing (if configured)

Degraded

Some failures, not critical yet

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

Action: Monitor closely, investigate if continues

Critical

Failure threshold exceeded

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

Action: Immediate investigation required

Maintenance

Scheduled maintenance window

Monitoring paused
No alerts sent
Status page shows “Maintenance”

Action: None - expected downtime

Monitoring Best Practices

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:

{
  "status": "healthy",
  "timestamp": "2025-01-19T10:30:00Z",
  "checks": {
    "database": "connected",
    "cache": "connected",
    "external_api": "reachable"
  }
}

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

Use Failure Thresholds Wisely

Prevent false alarmsNetwork blips are common:

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

Recommended configuration:

Failure Threshold: 3
Check Interval: 60 seconds
Detection Time: ~3 minutes

This balances:

✅ Fast detection (3 minutes)
✅ Filters false positives
✅ Reasonable alert frequency

Authenticate Health Checks

Protect sensitive endpointsOption 1: API Key Header

Headers:
  X-Health-Check-Token: secret-token-here

Option 2: Bearer Token

Headers:
  Authorization: Bearer your-api-key

Option 3: Custom Header

Headers:
  X-StatusStack-Monitor: true

Then whitelist StatusStack’s IP addresses in your firewall.

Monitor From User Perspective

Test what users experienceInstead 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

Maintenance Windows

Schedule downtime to prevent false alerts:

One-Time Maintenance

Open Monitor Settings

Navigate to your monitor and click “Schedule Maintenance”

Select Date & Time

Choose start and end times:

Start: January 25, 2025 at 2:00 AM UTC
End: January 25, 2025 at 4:00 AM UTC

Add Reason

Explain the maintenance (shown on status page):

"Database migration and server upgrades"

Save Maintenance

Monitor enters maintenance mode automatically at scheduled time

Recurring Maintenance

For regular maintenance windows:

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

Current Uptime

Last 24 hours
Last 7 days
Last 30 days
Last 90 days

Incident Statistics

Total incidents
Average duration
MTTR (Mean Time to Recovery)
Longest outage

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

Navigate to Notifications

Go to Settings → Notifications

Create Notification Rule

Click “Create Notification Rule”

Configure Trigger

Set when to alert:

Triggers:
  - Monitor becomes Critical
  - Monitor becomes Degraded (optional)
  - Monitor recovers
  - SSL certificate expiring (< 30 days)

Select Monitors

Choose which monitors trigger this rule:

All monitors
Specific monitors only
Monitors in specific Stacks

Choose Channels

Select notification channels:

Slack
Discord
Email
Microsoft Teams
PagerDuty
SMS (Twilio)

Save Rule

Activate the notification rule

See Notification Setup Guide for detailed configuration.

Troubleshooting

Monitor Showing as Down but Site is Up

Possible causes:

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

Solutions:

Check if endpoint is publicly accessible
Verify expected status code is correct
Increase timeout if endpoint is slow
Add authentication headers if required
Check SSL certificate expiration

False Positive Alerts

Issue: Getting alerts but service is actually up Solutions:

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

Monitor Not Creating Alerts

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

Notification rules are configured
Notification channels are working
Alert levels match (Critical vs Degraded)
Monitor is assigned to the right Stack
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

Notification Setup

Configure alerts for monitor failures

Adding to Stacks

Integrate monitors with your Stacks

Monitor Concepts

Deep dive into monitor architecture

Status Pages

Display monitors on public status pages

​Overview

​What Can You Monitor?

Public Websites

API Endpoints

Private Services

SSL Certificates

​Creating Your First Monitor

​Monitor Configuration

​Basic Settings

​Check Configuration

​Advanced Configuration

​Common Use Cases

​Example 1: Simple Website Monitoring

​Example 2: API Health Check with Authentication

​Example 3: Database Connectivity Check

​Example 4: Webhook Endpoint Monitoring

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

​Monitor Status Indicators

Operational

Degraded

Critical

Maintenance

​Monitoring Best Practices

​Maintenance Windows

​One-Time Maintenance

​Recurring Maintenance

​Monitor Analytics

​Uptime Metrics

Current Uptime

Incident Statistics

​Response Time Tracking

​Check History

​Notifications

​Creating Monitor Alerts

​Troubleshooting

​Monitor Showing as Down but Site is Up

​False Positive Alerts

​Monitor Not Creating Alerts

​Monitor Limits by Plan

​Next Steps

Notification Setup

Adding to Stacks

Monitor Concepts

Status Pages

Overview

What Can You Monitor?

Creating Your First Monitor

Monitor Configuration

Basic Settings

Check Configuration

Advanced Configuration

Common Use Cases

Example 1: Simple Website Monitoring

Example 2: API Health Check with Authentication

Example 3: Database Connectivity Check

Example 4: Webhook Endpoint Monitoring

Example 5: Multi-Region API Monitoring (Enterprise)

Monitor Status Indicators

Monitoring Best Practices

Maintenance Windows

One-Time Maintenance

Recurring Maintenance

Monitor Analytics

Uptime Metrics

Response Time Tracking

Check History

Notifications

Creating Monitor Alerts

Troubleshooting

Monitor Showing as Down but Site is Up

False Positive Alerts

Monitor Not Creating Alerts

Monitor Limits by Plan

Next Steps