strava-webhooks

Strava Webhooks

When to Use This Skill

• How do I receive Strava webhooks?
• How do I set up a Strava push subscription?
• How do I implement the Strava subscription validation (GET hub.challenge) handshake?
• Why is my Strava subscription creation failing / callback validation failing?
• How do I handle Strava activity and athlete events?
• How do I detect a Strava athlete deauthorization?

How Strava Webhooks Differ

Strava push events are NOT cryptographically signed — there is no per-event signature, HMAC, or shared-secret header to verify on each POST. Authenticity is established once, at subscription time, via a GET handshake:

1. You POST to https://www.strava.com/api/v3/push_subscriptions with client_id, client_secret, callback_url, and a self-chosen verify_token.
2. Strava immediately GETs your callback_url with hub.mode=subscribe, hub.challenge=<random>, and hub.verify_token=<your token>.
3. You confirm hub.verify_token matches your token and respond within 2 seconds with HTTP 200 and JSON body {"hub.challenge":"<echoed value>"}.

After that, Strava POSTs thin event payloads (an object_id, not full data) to the same callback. Acknowledge every event with 200 within 2 seconds or Strava retries (up to 3 total attempts). Fetch full activity/athlete data from the Strava REST API using the object_id. Only ONE subscription is allowed per API application.

Verification (core)

There is no signature to check on events — the security boundary is the GET validation handshake. Compare hub.verify_token against your stored token with a timing-safe comparison, then echo hub.challenge:

const crypto = require('crypto');

// GET /webhooks/strava — subscription validation handshake
function handleValidation(query, expectedToken) {
  const mode = query['hub.mode'];
  const token = query['hub.verify_token'] || '';
  const challenge = query['hub.challenge'];

  const a = Buffer.from(token);
  const b = Buffer.from(expectedToken);
  const tokenOk = a.length === b.length && crypto.timingSafeEqual(a, b);

  if (mode === 'subscribe' && tokenOk) {
    return { status: 200, body: { 'hub.challenge': challenge } }; // exact key name
  }
  return { status: 403, body: 'Forbidden' };
}