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.

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 must contain the hub.challenge token, ie. 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.

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.

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