Stride

Search Documentation

Search for articles, guides, and more

← API overview

Subscribe to events

POST/v1/app/webhooksrequires app.manage

Register a callback URL. One subscription covers every athlete who has authorized your app; each delivery names the athlete it is about, so route on athlete_id.

Before anything is delivered we verify the endpoint: Stride sends a GET to your URL with hub.mode=subscribe, hub.challenge and hub.verify_token query parameters, and your endpoint must answer 200 with {"hub.challenge": "<the challenge>"}. This is the same handshake Strava and Meta use. It exists so a mistyped URL cannot point Stride at a stranger's server.

The response carries the signing secret. It is shown once and is not recoverable.

Authenticate with a client_credentials token, not an athlete's token.

Example

bash
curl -X POST "https://api.stride.is/v1/app/webhooks" \
  -H "Authorization: Bearer $STRIDE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ }'

Response 201

Created. The Location header points at the new resource.

  • consecutive_failuresintegeralways present
  • created_atstringalways present
  • disabled_reasonstring
  • eventsstring[]always present
  • idstringalways present
  • last_delivery_atstring
  • secretstring
  • statusstringalways present
  • urlstringalways present

Errors

Every error is an RFC 9457 problem document. Branch on its code, which is stable; detail is prose and may be reworded.

  • 400The request was malformed: an unparseable date, an unknown enum value, or a parameter combination that cannot be satisfied.
  • 401No access token was supplied, or it is not valid for this API.
  • 402The Stride account the token belongs to has no active subscription or trial.
  • 403The token does not hold the scope this endpoint requires, or may not act on the athlete or team named.
  • 404No such resource, or it is not visible to this token. The two are deliberately indistinguishable.
  • 405The path exists but does not serve this method. The Allow header lists the ones it does.
  • 422The request was understood but could not be carried out: most often an upload that produced no activity.
  • 429A rate limit was exceeded. Retry after the period in the Retry-After header.
  • 500Something failed on Stride's side. The failure is logged with a trace ID.