# 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: Login & Auth Activity Monitoring
Track user sign-ins, brute-force attempts, and login errors across all applications:

### A. Universal Authentik SSO Webhook (Zero App Changes)
If your applications authenticate via Authentik, point an Authentik Event Webhook to Heartbeat to capture logins and errors across all apps automatically without touching application code:
- **Webhook Endpoint**: `POST /api/v1/logins/authentik-webhook`
- **Actions to route**: `login_failed`, `login`, `authorize_application`, `policy_execution_failed`

### B. Direct Application Ingestion API
For custom or non-SSO applications, POST authentication events directly:
```bash
curl -X POST "https://heartbeat.mtcd.org/api/v1/logins/ingest"   -H "Content-Type: application/json"   -d '{
    "app_slug": "snipeit",
    "username": "admin@mtcd.org",
    "status": "failed",
    "error_reason": "invalid_credentials",
    "error_message": "Invalid password entered 3 times",
    "ip_address": "198.51.100.42",
    "auth_method": "password"
  }'
```

---

## 5. Option D: 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.