Webhooks, metrics & integrations

Webhooks

Set a URL (and optional signing secret) in Settings → API. When a workout is finished — in the app or via the API — Forge POSTs:

{
  "event": "workout.finished",
  "source": "app",
  "workout": {
    "id": 123, "name": "Push Day",
    "started_at": "2026-07-17T17:30:00Z",
    "finished_at": "2026-07-17T18:35:00Z",
    "duration_seconds": 3900,
    "total_volume": 5480.0, "total_sets": 18, "pr_count": 1
  }
}

With a secret set, requests carry X-Forge-Signature: sha256=<HMAC-SHA256 of the raw body> for verification. Wire it to Home Assistant, n8n, a Discord relay — anything with an HTTP listener.

Prometheus metrics

GET /api/metrics emits text exposition — lifetime workout/set/volume/PR counters, streak weeks, current-week gauges, last-workout timestamp. Scrape with a read-only token:

scrape_configs:
  - job_name: forge
    metrics_path: /api/metrics
    scheme: https
    authorization:
      credentials: forge_pat_...
    static_configs:
      - targets: ["forge.example.com"]

Your streak on the same Grafana wall as your CPU graphs, where it belongs.

Dashboard widget (gethomepage)

GET /api/widget returns an at-a-glance JSON payload — streak, this week's progress vs your goal, week volume, last workout — designed for homepage's customapi widget with a read-only token:

- Forge:
    icon: mdi-weight-lifter
    href: https://forge.example.com
    widget:
      type: customapi
      url: https://forge.example.com/api/widget
      headers:
        Authorization: Bearer forge_pat_...
      mappings:
        - field: streak_weeks
          label: Streak (wks)
        - field: week_progress
          label: This week
        - field: week_volume
          label: Volume
        - field: last_workout
          label: Last session

Apple Health ingest (Health Auto Export)

Apple offers no server-side Health API, so Forge accepts the JSON the iOS Health Auto Export app POSTs on a schedule. Point an automation at POST /api/measurements/ingest with a full-access token; bodyweight (weight_body_mass) and body fat (body_fat_percentage) flow into Measurements — and from there into relative strength and the standards card. Re-exports are idempotent: duplicate timestamps are skipped.

MQTT / Home Assistant

Set the broker via environment variables and Forge publishes without any further setup:

Topics: forge/<username>/state (retained JSON mirroring /api/widget, refreshed on every finished workout) and forge/<username>/event/workout_finished. A Home Assistant sensor reads value_json.streak_weeks off the state topic.

Weekly digest

Settings → Insights → Weekly digest sends a Sunday-evening push notification over the same Web Push channel as rest alerts (HTTPS required): workouts vs goal, week volume with the week-over-week delta, and PRs. Sent once per week per user, only when there was training to report.