Subscriptions API Overview

The Subscriptions API is used to notify of changes in state of any of the Triathlon API resources. This is useful for example in keeping data synchronized with other services for example an external database that maintains a record of athlete profiles or for receiving live timing updates.

The simplest way to register a subscription is via the apps.api.triathlon.org management portal.

Receive webhook notifications for changes of state in the Triathlon APIReceive webhook notifications for changes of state in the Triathlon API

Receive webhook notifications for changes of state in the Triathlon API

Users may subscribe to any of the available methods e.g. athletes.edit, athletes.delete, rankings.publish and receive notifications via a webhook with the data being POSTed to the subscribed URL. Be aware that some methods my result in a large volume of data being POSTed to your servers, please ensure your applications can handle the load.

👍

Webhook endpoints should respond with a status of 2xx to indicate the message has been received

Available Methods

🚧

Not all methods currently available

Currently only rankings and live timing subscriptions are available.

The Subscription methods accept the following notifications. The method column indicates the name to use when registering a new subscription and is linked to the corresponding matching API call that would trigger it (useful for determining response types).

Method

Details

athlete.store

Fired on a creation of a new athlete

athlete.update

Fired on editing of an athlete

athlete.destroy

Fired on deleting of an athlete

athlete.merge

Fired on merging of two athlete profiles

team.store

Fired on creation of a new team

team.update

Fired on editing of a team

team.destroy

Fired on deleting of a team

event.store

Fired on creation of an event

event.update

Fired on updating of an event

event.destroy

Fired on deleting of an event

program.store

Fired on creation of a program

program.update

Fired on editing of a program

program.destroy

Fired on deleting of a program

entry.store

Fired on creation of a program entry

entry.update

Fired on editing of a program entry

entry.destroy

Fired on deleting of a program entry

results.store

Fired on creation of a result

results.update

Fired on updating of a result

results.destroy

Fired on deleting of a result

article.store

Fired on creation of an article

article.update

Fired on updating of an article

article.destroy

Fired on deletion of an article

web_image.store

Fired on creation of a web gallery image

hr_image.store

Fired on creation of a high-resolution gallery image

video.store

Fired on creation of a video

video.update

Fired on updating of a video

video.destroy

Fired on deletion of a video

download.store

Fired on creation of a download

download.update

Fired on updating of a download

download.destroy

Fired on deletion of a download

federation.store

Fired on creation of a Federation

federation.update

Fired on updating of a Federation

federation.destroy

Fired on deletion of a Federation

course.store

Fired on creation of a course

course.edit

Fired on updating of a course

course.destroy

Fired on deletion of a course

ranking.publish

Fired on rankings being published

subscription.store

Fired on creation of a subscription

subscription.update

Fired on updating of a subscription

subscription.destroy

Fired on deletion of a subscription

timing.store

Fired for a new live timing message

📘

Webhook Integration Services

Using services such as Zapier which may receive incoming webhooks you may integrate the Subscriptions API into a number of different services such as Twilio (if you wish to receive SMS messages), email or spreadsheet.

Retries

The Subscriptions API uses an exponential back-off style retry policy which increases the time delay between each retry. The Subscription API attempts 10 deliveries with an initial delay of 60 seconds. Should this fail you may include an email to be notified of a failed delivery which will occur after several hours of retries (see table below).

🚧

3xx responses will not be followed and will not be retried, only 4xx and 5xx responses

Retry Count

Next Retry

Total Seconds Elasped

1

61

61

2

76

137

3

141

217

4

361

457

5

685

1,001

6

1,356

2,041

7

2,461

3,817

8

4,156

6,617

9

6,621

10,777

10

10,060

16,681

Authentication

If authentication is required you may specify a token to be included in the incoming webhook which will be added as a URL parameter e.g. yoursite.com?token=my-secret-token

Debugging

The output of each of the webhooks corresponds to the method that is being called so you could consult the method documentation for the response type e.g. athletes.store responds with a 201 response and the same response as the calling method.

To debug webhooks consider using a service such as RequestBin to ensure you are receiving the response and then edit your subscription to match your production URL.