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 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 |
|---|---|
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 |
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.