Webhook Events

Webhook push subscriptions allow an application to subscribe to events that occur within Strava’s infrastructure. These events are pushed to a URL designated by the subscription. Webhooks allow an application to update athletes in real-time, and implement smarter data fetching.

Requests to the subscription endpoint are made using the client_id and client_secret of the application because requests are made on behalf of an application.

This API is only available to select applications. To request access please contact developers -at- strava.com.

Note: The hostname for this feature is different than normal API requests. Requests must be made to https://api.strava.com/

Also note: the request parameters must be sent in URL format (as opposed to JSON) as per the example to the right.

Push Subscription attributes

id:	integer
application_id:	integer The ID of the application that the push subscription belongs to
object_type:	string The object (for example: an activity) that is subscribed to. For the valid values, see Supported Subscriptions.
aspect_type:	string The aspect of the object that is subscribed to (for example: create), represented. For the valid values, see Supported Subscriptions.
callback_url:	string The URL that events will be posted to
created_at:	time string
updated_at:	time string

Supported Subscriptions

An application can subscribe to the following events. The integer values map to a specific object and aspect, as follows.

Activity Create

This subscription will receive events when a activity is uploaded or created manually. A push subscription for this event will receive a notification every time that an athlete that has authorized this application creates an activity.

object_type:	“activity”
aspect_type:	“create”

Create a subscription

The appliction must have permission to make use of the webhook API. Access can be requested by contacting developers -at- strava.com.

Parameters

client_id:	integer required application’s ID, obtained during registration
client_secret:	string required application’s secret, obtained during registration
object_type:	string required must match one of the supported object types
aspect_type:	string required must match one of the supported aspect types
callback_url:	string required maximum length of 255 characters
verify_token:	string user state specified by the user

Endpoint validation

The above request will send a GET request to callback url to verify existence: http://your-callback.com/url/?hub.mode=subscribe &hub.challenge=15f7d1a91c1f40f8a748fd134752feb3&hub.verify_token=STRAVA

hub.mode:	string will be set to ‘subscribe’
hub.challenge:	string random string the callback will need to echo back
hub.verify_token:	string This will be set to whatever verify_token passed in with the subscription request. It’s helpful to use this to differentiate between multiple subscription requests.

Your response to this GET request should be a JSON response, must contain the hub.challenge token, ie. {“hub.challenge”:”15f7d1a91c1f40f8a748fd134752feb3”} and have a response code of 200.

On callback verification we respond to the original POST with the created subscription. If there is an error, a response containing the reason for failure will be returned.

If the callback URL is an HTTPS endpoint, be sure to use a properly validated SSL cert and bundle.

Note: You can only subscribe one callback url per object and aspect types combination. Adding a new subscription automatically replaces existing subscription of that type.

Definition

POST https://api.strava.com/api/v3/push_subscriptions

Example request

$ curl -X POST https://api.strava.com/api/v3/push_subscriptions \
    -F client_id=5 \
    -F client_secret=7b2946535949ae70f015d696d8ac602830ece412 \
    -F 'object_type=activity' \
    -F 'aspect_type=create' \
    -F 'callback_url=http://a-valid.com/url' \
    -F 'verify_token=STRAVA' \

Example responses

{
  "hub.mode": "subscribe",
  "hub.verify_token": "STRAVA",
  "hub.challenge": "15f7d1a91c1f40f8a748fd134752feb3"
}

{
  "hub.challenge": "15f7d1a91c1f40f8a748fd134752feb3"
}

{
  "id": 1,
  "object_type": "activity",
  "aspect_type": "create",
  "callback_url": "http://a-valid.com/url",
  "created_at": "2015-04-29T18:11:09.400558047-07:00",
  "updated_at": "2015-04-29T18:11:09.400558047-07:00"
}

Receiving updates

When an event occurs that corresponds to a push subscription, a POST request will be made to the callback url defined in the subscription. The payload will contain the object and aspect types affected, as well as information about the object and its owner if applicable. The message payload includes the object_id that corresponds to the RESTful object the event corresponds to. For example, if the object is an activity, the object_id corresponds to an activity id.

You should acknowledge the POST within a 2 second timeout–if you need to do more processing of the received information, you can do so in an asynchronous task. Your endpoint should additionally return a status code of 200 to acknowledge receiving the event. If push is not acknowledged with a status code of 200 within 2 seconds, the event will be retried up to 3 times.

Additional metadata about the object is not included, and an application must decide how or if it wants to fetch updated data. For example, you may decide only to fetch new data for specific users, or after a certain number of activities have been uploaded.

Example POST body

{
  "subscription_id": "1",
  "owner_id": 13408,
  "object_id": 12312312312,
  "object_type": "activity",
  "aspect_type": "create",
  "event_time": 1297286541
}

List push subscriptions

This request is used to retrieve the summary representations of the push subscriptions in place for the current application.

Parameters

client_id:	integer required application’s ID, obtained during registration
client_secret:	string required application’s secret, obtained during registration

Attributes

id:	integer
object_type:	string object for which to get events, eg. ‘activity’
aspect_type:	string aspect for which to get events, eg. ‘create’
callback_url:	string
created_at:	time string
updated_at:	time string

Definition

GET https://api.strava.com/api/v3/push_subscriptions

Example request

$ curl -G https://api.strava.com/api/v3/push_subscriptions \
    -d client_id=5 \
    -d client_secret=7b2946535949ae70f015d696d8ac602830ece412

Example responses

[
  {
    "id": 1,
    "object_type": "activity",
    "aspect_type": "create",
    "callback_url": "http://you.com/callback/",
    "created_at": "2015-04-29T18:11:09.400558047-07:00",
    "updated_at": "2015-04-29T18:11:09.400558047-07:00"
  }
]

Delete a subscription

This request is used to unsubscribe from events.

Parameters

id:	integer required
client_id:	integer required application’s ID, obtained during registration
client_secret:	string required application’s secret, obtained during registration,

If the delete is successful, a 204 will be returned. Otherwise, an error will be returned containing the reason for a failure.

Definition

DELETE https://api.strava.com/api/v3/push_subscriptions/:id