Migrate from polling to webhooks for a fitness API

Migrate from polling to webhooks

You are moving an existing fitness integration from scheduled polling to webhook-driven updates: instead of your backend asking the provider "anything new?" on a timer, the provider pushes an event the moment data changes. The single biggest gotcha is that many providers send a notification, not the data — the webhook says "new activity, id=X" and you still have to fetch the full record. This is a real re-integration with new plumbing (an HTTPS endpoint, signature verification, a queue, idempotency, and a reconciliation fallback), not a flag you flip. Plan to run polling and webhooks in parallel and keep a low-frequency poll as a permanent safety net.

Why make the move

• Freshness. Push delivers new data near-real-time, instead of waiting for the next scheduled poll to come around.
• Rate-limit pressure. Polling burns request budget on unchanged data; webhooks fire only when something actually changes. As an example, Strava's documented defaults are around 200 requests per 15 minutes and roughly 2,000 per day overall (with a lower non-upload limit) — treat those as illustrative and verify current numbers in the provider docs.
• Cost and efficiency. Fewer wasted calls means less compute and less throttling risk at scale.

If you are new to the mechanics, see what are webhooks — this page does not re-explain the concept, it covers the migration.

What actually changes

A key nuance: not all providers send the same payload shape. Strava's webhook events carry object and aspect ids rather than the full activity, so you fetch afterward. Terra can deliver normalized data in the webhook itself but sends large historical ranges (documented as over 28 days) asynchronously in chunks. Design for both shapes and verify per provider.

The migration, step by step

1. Stand up an HTTPS endpoint and implement the verification handshake. Most providers validate your endpoint with a challenge/response before they will deliver events; return the expected token to prove you own it.
2. Verify signatures on every request. Providers typically sign the raw body with an HMAC secret. Compute over the raw bytes, use a constant-time compare, require HTTPS, support secret rotation, and reject stale timestamps to blunt replay.
3. Register the webhook subscription — and mind per-app subscription caps. Some providers limit how many subscriptions an app can hold; Strava is documented as one push subscription per application (verify current limits).
4. Acknowledge fast, process async. On receipt: verify, return a 2xx immediately, and enqueue the event for a worker. Doing heavy work synchronously causes timeouts, which trigger provider retries and duplicate deliveries.
5. In the worker, dedupe then fetch. Dedupe on the provider's unique event id (keep the dedupe store longer than the provider's retry window), then fetch the full record if the payload was only a notification.
6. Guard ordering and handle retries. Delivery is unordered and at-least-once — use timestamps or version numbers so a stale event never overwrites newer state, and dead-letter poison events for later inspection.
7. Keep a scheduled reconciliation poll as a fallback and gap back-fill. Webhooks miss during endpoint downtime or dropped deliveries; a low-frequency poll catches what the push stream drops.
8. Ramp webhook traffic while polling runs in parallel. Once webhook coverage is verified against the poll, reduce polling to the low-frequency safety net rather than removing it.

Gotchas and how to keep the data flowing

• Do not assume the payload contains the data. Check each provider — some push the record, some push only an id you must fetch. Building for one shape and getting the other silently loses data.
• At-least-once means duplicates are normal. Without idempotency keyed on the event id, retries double-process events. Without an ordering guard, an out-of-order delivery can roll back good state.
• Webhooks are best-effort, not guaranteed. There is no built-in catch-up for an outage on your side, which is why the reconciliation poll stays in place permanently, not just during cutover.
• Subscription caps constrain architecture. If a provider allows only one subscription per app, you cannot spin up a separate subscription per environment casually — plan routing accordingly and verify the cap.

If your webhook stops arriving after setup, the symptom-level checklist lives in Strava webhook not firing. If you would rather one integration normalize many providers' webhook streams into a single schema, that trade-off is covered under health data aggregator APIs.

How much effort is this really

Budget for it as a genuine re-integration: a secured endpoint, a queue and worker, idempotency and ordering logic, and a fallback poll — plus a parallel-run window to prove coverage before you dial polling down. None of the specifics here (rate limits, retry counts, timeout windows, subscription caps) are safe to hardcode; they shift, so verify the current provider docs as of 2026 before you build against any number.