fitops webhooks

Manage Strava webhook sync.

Webhooks let Strava call your FitOps backend when an activity is created, updated, or deleted. When webhook sync is enabled, FitOps stops the dashboard's periodic Strava polling and uses these events as the primary sync trigger.

TIP

Strava requires a public HTTPS callback URL. Webhook sync is supported for deployed FitOps dashboard servers. The normal local dashboard at localhost cannot receive Strava webhooks.

Commands

Choosing the Callback URL

The callback URL is the public address Strava calls. It must point to the running FitOps dashboard and end with:

/api/strava/webhook

Use the URL for the deployed dashboard that is actually reachable from Strava:

Environment	Callback URL
HuggingFace Space	https://<space-host>/api/strava/webhook
Other deployed server	https://<your-domain>/api/strava/webhook
Local dashboard	Not supported for webhook sync; use polling or manual sync

http://localhost:8888/api/strava/webhook only works for requests from your own machine. Strava cannot reach your laptop's localhost. For local FitOps use, keep sync mode as polling or manual.

HF deployments created with fitops deploy hf set the callback URL automatically and register the Strava push subscription after Strava credentials are restored or completed in the Space setup flow. Use fitops webhooks setup for non-HF deployed dashboards, or to repair/change a subscription manually.

fitops webhooks setup creates the Strava push subscription through Strava's API using the Strava app client_id and client_secret already saved during auth setup. If the Strava developer settings page asks for an Authorization Callback Domain, use the deployed host only, without https:// and without the path. For example, for https://myuser-fitops-dashboard.hf.space/api/strava/webhook, enter myuser-fitops-dashboard.hf.space.

fitops webhooks setup

Create a Strava push subscription and switch FitOps to webhook sync mode.

fitops webhooks setup --callback-url https://example.com/api/strava/webhook

Examples:

# HuggingFace Space dashboard
fitops webhooks setup --callback-url https://my-fitops.hf.space/api/strava/webhook

For HF deployments, fitops deploy hf stores the exact callback URL on the Space and prints it for reference.

Flag	Default	Description
--callback-url URL	required	Public URL where Strava sends webhook verification and event requests
--verify-token TOKEN	generated	Optional Strava verification token
--json	false	Print structured JSON

fitops webhooks status

Show local webhook configuration, remote subscription status, current sync mode, and recent received events.

fitops webhooks status --json

{
  "_meta": {
    "tool": "fitops",
    "version": "0.1.0",
    "generated_at": "2026-05-16T12:00:00+00:00",
    "total_count": 1,
    "filters_applied": {}
  },
  "webhook": {
    "configured": true,
    "enabled": true,
    "callback_url": "https://example.com/api/strava/webhook",
    "subscription_id": 12345,
    "sync_mode": "webhook",
    "recent_events": []
  }
}

fitops webhooks mode

Set the dashboard sync mode without changing the Strava subscription.

fitops webhooks mode webhook
fitops webhooks mode polling
fitops webhooks mode manual

Mode	Behavior
webhook	Strava webhook events trigger activity create/update/delete processing
polling	The dashboard uses the existing periodic incremental sync fallback
manual	No automatic Strava sync; use fitops sync run or the dashboard Sync button

fitops webhooks delete

Delete the Strava push subscription and return FitOps to polling mode.

fitops webhooks delete

Event Behavior

Strava event	FitOps behavior
activity/create	Imports the activity, fetches streams and weather, computes cached metrics, matches plans, and triggers backup sync if configured
activity/update	Refreshes the activity from Strava and refreshes dependent cached data
activity/delete	Removes the activity and dependent local rows, including streams, weather, laps, workout links, race links, and cached activity artifacts

FitOps records webhook events locally so duplicate Strava deliveries are ignored and recent processing status is visible in the dashboard.

See Also

• fitops sync
• Dashboard Backup & Sync