Incidents

Incidents are how you communicate service disruptions to your users. When something goes wrong, create an incident to keep users informed.

Creating Incidents

From Dashboard

1. Go to Dashboard → Incidents
2. Click Create Incident
3. Fill in the details:
   • Title: Clear, descriptive summary
   • Description: What's happening
   • Severity: Major, Minor, or Maintenance
   • Affected Components: Which monitors are impacted
4. Click Create

From API

curl -X POST "https://statly.live/api/v1/incidents" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Performance Degradation",
    "description": "We are investigating slow response times on the API.",
    "severity": "minor",
    "status": "investigating"
  }'

Incident Status

Update the status as you work through the incident:

Severity Levels

Incident Updates

Add updates as the situation evolves:

12:00 PM - Investigating
"We're aware of slow API response times and are investigating."

12:15 PM - Identified
"We've identified the issue as a database connection pool exhaustion."

12:30 PM - Monitoring
"A fix has been deployed. We're monitoring for stability."

1:00 PM - Resolved
"All systems are operating normally. The issue was caused by..."

Adding Updates via API

curl -X PATCH "https://statly.live/api/v1/incidents/{id}" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "identified",
    "message": "Root cause identified as database connection pool exhaustion."
  }'

Affected Components

Link incidents to specific monitors/components:

1. When creating an incident, select affected components
2. Those components will show degraded/outage status
3. When resolved, components automatically return to operational

Notifications

Subscribers receive notifications for:

• New incidents (major severity)
• Status changes (investigating → resolved)
• New updates (optional per subscriber)

Email Notifications

Emails are sent via Cloudflare MailChannels with your organization's branding:

• Subject: [Statly] Incident: {title}
• From: status@{your-org}.statly.live
• Unsubscribe link included

Scheduled Maintenance

Create maintenance windows to inform users of planned downtime:

1. Create incident with severity maintenance
2. Set scheduled start/end times
3. Users see upcoming maintenance on the status page
4. Optionally auto-create incident when maintenance starts

curl -X POST "https://statly.live/api/v1/incidents" \
  -H "Authorization: Bearer sk_live_xxx" \
  -d '{
    "title": "Scheduled Database Maintenance",
    "severity": "maintenance",
    "scheduledStart": "2024-01-15T02:00:00Z",
    "scheduledEnd": "2024-01-15T04:00:00Z"
  }'

Best Practices

Clear Communication

• Be specific: "API returning 500 errors" not "Having issues"
• Set expectations: "Estimated resolution in 30 minutes"
• Update frequently: Users prefer frequent updates over silence
• Post-mortem: After major incidents, share what happened and preventive measures

Automation

Integrate incident creation with your alerting:

// Example: Create incident from PagerDuty webhook
async function handleAlert(alert) {
  if (alert.severity === 'critical') {
    await fetch('https://statly.live/api/v1/incidents', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.STATLY_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        title: alert.title,
        description: alert.description,
        severity: 'major',
        status: 'investigating',
      }),
    });
  }
}

API Reference

See API Reference → Incidents for complete documentation.