# Heartbeat WebApp Integration Guide

Connect your web applications to Heartbeat to enable automated uptime health checks and tiered error alerting.

---

## 1. Quick Registration
Register your web application with Heartbeat via `POST /api/v1/apps`:

```bash
curl -X POST "http://:8000/api/v1/apps" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-webapp",
    "url": "https://my-webapp.domain.com",
    "api_key": "optional-secret-key",
    "heartbeat_endpoint": "/api/heartbeat",
    "poll_interval": 60,
    "consecutive_failures_threshold": 2
  }'
```

---

## 2. Option A: WebApp Exposes a Heartbeat Endpoint (Pull Model)
Heartbeat will periodically ping your app at `GET /api/heartbeat`.

### Request from Heartbeat
- **Method**: `GET`
- **Headers**:
  - `X-API-Key: `
  - `Authorization: Bearer `

### Expected Response from your WebApp
- **HTTP Status**: `200 OK` (any `2xx` is treated as Healthy; `5xx` or timeout is treated as Down).
- **JSON Body (Recommended)**:
```json
{
  "status": "healthy",
  "version": "1.2.0",
  "database": "connected",
  "timestamp": "2026-09-14T18:00:00Z"
}
```

---

## 3. Option B: Push Real-Time Errors & Heartbeats (Push Model)
Your application can push events and errors directly to Heartbeat as they happen.

### Report an Error (`POST /api/v1/ingest/errors`)
Errors are grouped into three distinct severity levels:
- **`logged`**: Stored in the database for tracking. No instant notifications are sent.
- **`important`**: Triggers a notification (e.g. email delivery failure, payment retry).
- **`critical`**: Triggers an urgent immediate alert (e.g. database connection lost, auth provider unreachable).

```bash
curl -X POST "http://:8000/api/v1/ingest/errors" \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "my-webapp",
    "api_key": "optional-secret-key",
    "severity": "important",
    "error_message": "User login failure spike detected",
    "details": "Failed 15 consecutive login attempts from IP 192.168.1.50",
    "metadata": {
      "ip": "192.168.1.50",
      "attempts": 15
    }
  }'
```

---

## 4. Option C: AI Agent Custom Probes
For applications that cannot expose an API endpoint (e.g., Home Assistant, Synology DSM, external websites), use the Custom Probes API:
- `POST /api/v1/probes/test`: Validate a Python script or HTTP assertion snippet.
- `POST /api/v1/probes`: Register the probe to run continuously on a set poll interval.