Status & SLA

Health Check Endpoints

All health check endpoints are unauthenticated and return JSON with a status field that can be healthy, degraded, down, or disabled.

Aggregate Health

GET /api/v1/health/all

Checks all services in parallel and returns an aggregated status. This is the recommended endpoint for monitoring systems and status pages.

{
  "status": "healthy",
  "timestamp": "2026-07-25T12:00:00.000Z",
  "total_latency_ms": 142,
  "services": [
    { "service": "database", "status": "healthy", "latency_ms": 0 },
    { "service": "api-gateway", "status": "healthy", "latency_ms": 45 },
    { "service": "websocket", "status": "healthy", "latency_ms": 32 },
    { "service": "cloud-storage", "status": "healthy", "latency_ms": 18 },
    { "service": "whatsapp", "status": "healthy", "latency_ms": 67 },
    { "service": "firewall", "status": "healthy", "latency_ms": 12 },
    { "service": "freeswitch", "status": "healthy", "latency_ms": 28 }
  ],
  "summary": {
    "healthy": 7,
    "degraded": 0,
    "down": 0,
    "disabled": 0,
    "total": 7
  }
}

Individual Service Health

Response Format

All health endpoints return:

{
  "status": "healthy | degraded | down | disabled",
  "service": "service-name",
  "latency_ms": 42,
  "timestamp": "2026-07-25T12:00:00.000Z"
}

• healthy — Service is fully operational
• degraded — Service is responding but with issues (slow, partial failures)
• down — Service is unreachable or returning errors
• disabled — Service is intentionally disabled (e.g., FreeSWITCH not enabled)

SLA Tiers

API Uptime SLA

Webhook Delivery SLA

• Delivery rate: 99.5% of webhooks delivered within 30 seconds
• Retry policy: Up to 5 retries with exponential backoff (1s, 5s, 30s, 2m, 10m)
• Dead letter queue: Failed deliveries after all retries are moved to DLQ
• DLQ retention: 30 days, then auto-expired

Support Response SLA

Maintenance Windows

• Scheduled maintenance does not count against SLA
• Maintenance is announced at least 48 hours in advance
• Maintenance windows are published on the status page
• Emergency maintenance may be performed with shorter notice

Monitoring Integration

Polling Health Endpoints

# Check all services
curl https://dev-next.totalaccess.co.za/api/v1/health/all

# Check individual service
curl https://dev-next.totalaccess.co.za/api/v1/health/websocket

Prometheus / Grafana

The existing Grafana/Prometheus monitoring stack can scrape these endpoints. Each service also exposes a /metrics endpoint with Prometheus-format metrics.

Recommended Polling Interval

• Status page: Every 30 seconds
• Alerting: Every 10 seconds (with 3 consecutive failures before alerting)
• Dashboard: Every 60 seconds