API-Referenz – LaraFleet

Authentifizierung

Jede Anfrage an den Heartbeat-Endpoint wird per HMAC-SHA256 signiert. Die Signatur basiert auf dem Projekt-API-Key und dem Anfrage-Body.

LaraFleet prüft zusätzlich einen Timestamp-Header mit einer Toleranz von ±60 Sekunden. Anfragen außerhalb dieses Fensters werden als Replay-Angriff zurückgewiesen.

# Request-Header

X-LaraFleet-Signature: sha256=<hmac>

X-LaraFleet-Timestamp: 1717056000

Content-Type: application/json

Heartbeat-Endpoint

POST https://app.larafleet.com/api/heartbeat

Nimmt den signierten Heartbeat-Payload entgegen und speichert ihn als Snapshot.

Rate Limit: 1 Request / Minute pro API-Key.

Request-Payload (Full Heartbeat)

heartbeat.json

{
  "type": "full",
  "timestamp": 1717056000,
  "laravel_version": "11.28.0",
  "php_version": "8.3.6",
  "php_extensions": ["bcmath", "ctype", "curl", ...],
  "composer_packages": [
    {
      "name": "laravel/framework",
      "installed": "11.28.0",
      "latest": "11.28.0",
      "outdated_type": null
    }
  ],
  "composer_advisories": [
    {
      "package": "laravel/framework",
      "cve": "CVE-2024-47868",
      "severity": "high",
      "title": "..."
    }
  ],
  "npm_packages": [
    {
      "name": "vite",
      "installed": "5.4.0",
      "latest": "5.4.2",
      "outdated_type": "patch"
    }
  ],
  "npm_advisories": [
    {
      "ghsa": "GHSA-xxxx-xxxx-xxxx",
      "cve": "CVE-2024-00000",
      "severity": "moderate",
      "module_name": "example-pkg"
    }
  ],
  "queue": {
    "failed_jobs": 0,
    "size": 2
  },
  "scheduler": {
    "last_run_at": "2024-05-30T09:00:00Z",
    "missed": false
  },
  "disk_usage_mb": 1240,
  "storage_usage_mb": 340,
  "env_snapshot": {
    "APP_ENV": "production",
    "APP_DEBUG": "false"
  },
  "deployment_at": "2024-05-29T14:30:00Z",
  "deployment_hash": "a3f2d1c"
}

Request-Payload (Quick Heartbeat)

{
  "type": "quick",
  "timestamp": 1717056300,
  "queue": {
    "failed_jobs": 0,
    "size": 0
  },
  "scheduler": {
    "last_run_at": "2024-05-30T09:05:00Z",
    "missed": false
  },
  "disk_usage_mb": 1240
}

Exception-Endpoint

POST https://app.larafleet.com/api/exceptions

Empfängt einen einzelnen Exception-Report vom Agent. Gleiche HMAC-SHA256-Authentifizierung wie der Heartbeat-Endpoint.

Rate Limit: 60 Requests / Minute pro API-Key (eine Seite kann mehrere verschiedene Exceptions pro Minute werfen).

exception.json

{
  "exception": {
    "class": "App\\Exceptions\\PaymentException",
    "message": "Stripe charge failed: card_declined",
    "file": "/var/www/html/app/Services/PaymentService.php",
    "line": 42,
    "trace": [
      "/var/www/html/app/Services/PaymentService.php:42 App\\Services\\PaymentService->charge",
      "/var/www/html/app/Http/Controllers/CheckoutController.php:78 App\\Http\\Controllers\\CheckoutController->store"
    ],
    "fingerprint": "a3f2d1c4e5b6..."
  },
  "request": {
    "url": "https://example.com/checkout",
    "method": "POST",
    "query": { "ref": "campaign_x" },
    "input": { "token": "[FILTERED]" },
    "user_id": 12
  },
  "context": {
    "laravel_version": "11.44.0",
    "php_version": "8.3.30",
    "environment": "production"
  },
  "occurred_at": "2026-06-29T10:34:12+00:00"
}

Hinweise

·exception.fingerprint — sha256(class + message + file + line), 64-stelliger Hex-String, vom Agent berechnet. Gleicher Fingerprint erhöht nur den Occurrence-Counter.
·request — null bei CLI-Kontext (Artisan Commands). Sensible Felder (password, token etc.) werden durch [FILTERED] ersetzt; URL ohne Query-String.
·occurred_at — ISO-8601-Timestamp; wird als first_seen_at / last_seen_at in der Zentrale gespeichert.
·Sicherheit: gleiche HMAC-SHA256-Signatur + Timestamp-Replay-Schutz (±60 s) wie beim Heartbeat.

Status	Bedeutung
200 OK	Exception erfasst (neu, dedupliziert oder re-opened)
401 Unauthorized	Ungültiger oder fehlender API-Key
403 Forbidden	HMAC-Signatur ungültig
422 Unprocessable	Timestamp außerhalb ±60 s oder Pflichtfelder fehlen
429 Too Many Requests	Rate Limit überschritten (60 req/min)

Response (Heartbeat)

Status	Bedeutung
200 OK	Heartbeat erfolgreich gespeichert
401 Unauthorized	Ungültige oder fehlende Signatur
422 Unprocessable	Payload-Validierungsfehler
429 Too Many Requests	Rate Limit überschritten (1 req/min)

Env-Whitelist

Der env_snapshot enthält nur explizit freigegebene Keys. Standardmäßig sind folgende Keys enthalten:

APP_ENV APP_DEBUG APP_URL DB_CONNECTION CACHE_DRIVER QUEUE_CONNECTION SESSION_DRIVER MAIL_MAILER

Die Whitelist kann in config/larafleet-agent.php angepasst werden. Sensible Keys wie DB_PASSWORD oder APP_KEY werden niemals übertragen.