{"__v":51,"_id":"564b86fe7a18b00d00a21bec","category":{"__v":6,"_id":"55773af307e7110d001043ef","pages":["564b86fe7a18b00d00a21bec","564b8711d768500d0088b712","564b87210a68360d00a3a536","564b87367a18b00d00a21bef","564b874a7a18b00d00a21bf2","564b876425d7060d005c58a4"],"project":"55773a5ba042551900b002cb","version":"55773a5ba042551900b002ce","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-06-09T19:13:55.100Z","from_sync":false,"order":10,"slug":"subscriptions-api","title":"Subscriptions API"},"parentDoc":null,"project":"55773a5ba042551900b002cb","user":"546d17e2eb9cfd1400dd4529","version":{"__v":17,"_id":"55773a5ba042551900b002ce","project":"55773a5ba042551900b002cb","createdAt":"2015-06-09T19:11:23.764Z","releaseDate":"2015-06-09T19:11:23.764Z","categories":["55773a5ca042551900b002cf","55773a6ce6063e0d00481380","55773ab007e7110d001043ec","55773abaa042551900b002d5","55773ac207e7110d001043ed","55773acb07e7110d001043ee","55773ad3a042551900b002d6","55773adce6063e0d00481383","55773ae4a042551900b002d7","55773af307e7110d001043ef","55773af907e7110d001043f0","55773b0407e7110d001043f1","563a4f7ad25e8919005f3f39","563a4fcaa19edf0d00972321","564a70dc4cd0521700523edf","564b797bcc472d0d00da9435","564b855b766d4923004e1fd1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Motherboard","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-17T19:58:54.666Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"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.\n\nThe simplest way to register a subscription is via the [apps.api.triathlon.org](https://apps.api.triathlon.org/) management portal.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/mZZ0P6upTSukrc7kR9wX_hamburg-team-msj_37.jpg\",\n        \"hamburg-team-msj_37.jpg\",\n        \"1629\",\n        \"1084\",\n        \"#5488e8\",\n        \"\"\n      ],\n      \"caption\": \"Receive webhook notifications for changes of state in the Triathlon API\"\n    }\n  ]\n}\n[/block]\nUsers 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.\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Webhook endpoints should respond with a status of 2xx to indicate the message has been received\"\n}\n[/block]\nLive methods are not covered by the subscription API and you should consult the documentation for the Live API and companion Streaming API for further details.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available Methods\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Not all methods currently available\",\n  \"body\": \"Currently only rankings and live timing subscriptions are available.\"\n}\n[/block]\nThe 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).\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Details\",\n    \"0-0\": \"[athlete.store](https://developers.triathlon.org/docs/create-an-athlete)\",\n    \"1-0\": \"athlete.update\",\n    \"2-0\": \"athlete.destroy\",\n    \"0-1\": \"Fired on a creation of a new athlete\",\n    \"1-1\": \"Fired on editing of an athlete\",\n    \"2-1\": \"Fired on deleting of an athlete\",\n    \"4-0\": \"team.store\",\n    \"5-0\": \"team.update\",\n    \"6-0\": \"team.destroy\",\n    \"7-0\": \"event.store\",\n    \"8-0\": \"event.update\",\n    \"9-0\": \"event.destroy\",\n    \"10-0\": \"program.store\",\n    \"11-0\": \"program.update\",\n    \"12-0\": \"program.destroy\",\n    \"13-0\": \"entry.store\",\n    \"14-0\": \"entry.update\",\n    \"15-0\": \"entry.destroy\",\n    \"16-0\": \"result.store\",\n    \"17-0\": \"results.update\",\n    \"18-0\": \"result.destroy\",\n    \"19-0\": \"article.store\",\n    \"20-0\": \"article.update\",\n    \"21-0\": \"article.destroy\",\n    \"22-0\": \"web_image.store\",\n    \"23-0\": \"hr_image.store\",\n    \"24-0\": \"video.store\",\n    \"25-0\": \"video.update\",\n    \"26-0\": \"video.destroy\",\n    \"27-0\": \"download.store\",\n    \"28-0\": \"download.update\",\n    \"29-0\": \"download.destroy\",\n    \"30-0\": \"federation.store\",\n    \"31-0\": \"federation.update\",\n    \"32-0\": \"federation.destroy\",\n    \"33-0\": \"course.store\",\n    \"34-0\": \"course.edit\",\n    \"35-0\": \"course.destroy\",\n    \"36-0\": \"ranking.run\",\n    \"37-0\": \"ranking.publish\",\n    \"38-0\": \"subscription.store\",\n    \"39-0\": \"subscription.update\",\n    \"40-0\": \"subscription.destroy\",\n    \"4-1\": \"Fired on creation of a new team\",\n    \"5-1\": \"Fired on editing of a team\",\n    \"6-1\": \"Fired on deleting of a team\",\n    \"3-0\": \"athlete.merge\",\n    \"3-1\": \"Fired on merging of two athlete profiles\",\n    \"7-1\": \"Fired on creation of an event\",\n    \"8-1\": \"Fired on updating of an event\",\n    \"9-1\": \"Fired on deleting of an event\",\n    \"10-1\": \"Fired on creation of a program\",\n    \"11-1\": \"Fired on editing of a program\",\n    \"12-1\": \"Fired on deleting of a program\",\n    \"13-1\": \"Fired on creation of a program entry\",\n    \"14-1\": \"Fired on editing of a program entry\",\n    \"15-1\": \"Fired on deleting of a program entry\",\n    \"16-1\": \"Fired on creation of a result\",\n    \"17-1\": \"Fired on updating of a result\",\n    \"18-1\": \"Fired on deleting of a result\",\n    \"19-1\": \"Fired on creation of an article\",\n    \"20-1\": \"Fired on updating of an article\",\n    \"21-1\": \"Fired on deletion of an article\",\n    \"22-1\": \"Fired on creation of a web gallery image\",\n    \"23-1\": \"Fired on creation of a high-resolution gallery image\",\n    \"24-1\": \"Fired on creation of a video\",\n    \"25-1\": \"Fired on updating of a video\",\n    \"26-1\": \"Fired on deletion of a video\",\n    \"27-1\": \"Fired on creation of a download\",\n    \"28-1\": \"Fired on updating of a download\",\n    \"29-1\": \"Fired on deletion of a download\",\n    \"30-1\": \"Fired on creation of a Federation\",\n    \"33-1\": \"Fired on creation of a course\",\n    \"38-1\": \"Fired on creation of a subscription\",\n    \"31-1\": \"Fired on updating of a Federation\",\n    \"34-1\": \"Fired on updating of a course\",\n    \"39-1\": \"Fired on updating of a subscription\",\n    \"32-1\": \"Fired on deletion of a Federation\",\n    \"35-1\": \"Fired on deletion of a course\",\n    \"40-1\": \"Fired on deletion of a subscription\",\n    \"36-1\": \"Fired on rankings being run\",\n    \"37-1\": \"Fired on rankings being published\",\n    \"41-0\": \"[timing.store](https://developers.triathlon.org/docs/live-timing)\",\n    \"41-1\": \"Fired for a new live timing message\"\n  },\n  \"cols\": 2,\n  \"rows\": 42\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Webhook Integration Services\",\n  \"body\": \"Using services such as [Zapier](http://zapier.com) 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.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Retries\"\n}\n[/block]\nThe 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).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"3xx responses will not be followed and will not be retried, only 4xx and 5xx responses\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"1\",\n    \"h-0\": \"Retry Count\",\n    \"h-1\": \"Next Retry\",\n    \"h-2\": \"Total Seconds Elasped\",\n    \"9-0\": \"10\",\n    \"1-0\": \"2\",\n    \"2-0\": \"3\",\n    \"3-0\": \"4\",\n    \"4-0\": \"5\",\n    \"5-0\": \"6\",\n    \"6-0\": \"7\",\n    \"7-0\": \"8\",\n    \"8-0\": \"9\",\n    \"0-1\": \"61\",\n    \"0-2\": \"61\",\n    \"1-1\": \"76\",\n    \"2-1\": \"141\",\n    \"3-1\": \"361\",\n    \"4-1\": \"685\",\n    \"5-1\": \"1,356\",\n    \"6-1\": \"2,461\",\n    \"7-1\": \"4,156\",\n    \"8-1\": \"6,621\",\n    \"9-1\": \"10,060\",\n    \"1-2\": \"137\",\n    \"2-2\": \"217\",\n    \"3-2\": \"457\",\n    \"4-2\": \"1,001\",\n    \"5-2\": \"2,041\",\n    \"6-2\": \"3,817\",\n    \"7-2\": \"6,617\",\n    \"8-2\": \"10,777\",\n    \"9-2\": \"16,681\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nIf 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\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Debugging\"\n}\n[/block]\nThe 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](https://developers.triathlon.org/docs/create-an-athlete). \n\nTo debug webhooks consider using a service such as [RequestBin](http://requestb.in/) to ensure you are receiving the response and then edit your subscription to match your production URL.","excerpt":"","slug":"subscriptions-api-overview","type":"basic","title":"Subscriptions API Overview"}

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](https://apps.api.triathlon.org/) management portal. [block:image] { "images": [ { "image": [ "https://files.readme.io/mZZ0P6upTSukrc7kR9wX_hamburg-team-msj_37.jpg", "hamburg-team-msj_37.jpg", "1629", "1084", "#5488e8", "" ], "caption": "Receive webhook notifications for changes of state in the Triathlon API" } ] } [/block] 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. [block:callout] { "type": "success", "title": "Webhook endpoints should respond with a status of 2xx to indicate the message has been received" } [/block] Live methods are not covered by the subscription API and you should consult the documentation for the Live API and companion Streaming API for further details. [block:api-header] { "type": "basic", "title": "Available Methods" } [/block] [block:callout] { "type": "warning", "title": "Not all methods currently available", "body": "Currently only rankings and live timing subscriptions are available." } [/block] 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). [block:parameters] { "data": { "h-0": "Method", "h-1": "Details", "0-0": "[athlete.store](https://developers.triathlon.org/docs/create-an-athlete)", "1-0": "athlete.update", "2-0": "athlete.destroy", "0-1": "Fired on a creation of a new athlete", "1-1": "Fired on editing of an athlete", "2-1": "Fired on deleting of an athlete", "4-0": "team.store", "5-0": "team.update", "6-0": "team.destroy", "7-0": "event.store", "8-0": "event.update", "9-0": "event.destroy", "10-0": "program.store", "11-0": "program.update", "12-0": "program.destroy", "13-0": "entry.store", "14-0": "entry.update", "15-0": "entry.destroy", "16-0": "result.store", "17-0": "results.update", "18-0": "result.destroy", "19-0": "article.store", "20-0": "article.update", "21-0": "article.destroy", "22-0": "web_image.store", "23-0": "hr_image.store", "24-0": "video.store", "25-0": "video.update", "26-0": "video.destroy", "27-0": "download.store", "28-0": "download.update", "29-0": "download.destroy", "30-0": "federation.store", "31-0": "federation.update", "32-0": "federation.destroy", "33-0": "course.store", "34-0": "course.edit", "35-0": "course.destroy", "36-0": "ranking.run", "37-0": "ranking.publish", "38-0": "subscription.store", "39-0": "subscription.update", "40-0": "subscription.destroy", "4-1": "Fired on creation of a new team", "5-1": "Fired on editing of a team", "6-1": "Fired on deleting of a team", "3-0": "athlete.merge", "3-1": "Fired on merging of two athlete profiles", "7-1": "Fired on creation of an event", "8-1": "Fired on updating of an event", "9-1": "Fired on deleting of an event", "10-1": "Fired on creation of a program", "11-1": "Fired on editing of a program", "12-1": "Fired on deleting of a program", "13-1": "Fired on creation of a program entry", "14-1": "Fired on editing of a program entry", "15-1": "Fired on deleting of a program entry", "16-1": "Fired on creation of a result", "17-1": "Fired on updating of a result", "18-1": "Fired on deleting of a result", "19-1": "Fired on creation of an article", "20-1": "Fired on updating of an article", "21-1": "Fired on deletion of an article", "22-1": "Fired on creation of a web gallery image", "23-1": "Fired on creation of a high-resolution gallery image", "24-1": "Fired on creation of a video", "25-1": "Fired on updating of a video", "26-1": "Fired on deletion of a video", "27-1": "Fired on creation of a download", "28-1": "Fired on updating of a download", "29-1": "Fired on deletion of a download", "30-1": "Fired on creation of a Federation", "33-1": "Fired on creation of a course", "38-1": "Fired on creation of a subscription", "31-1": "Fired on updating of a Federation", "34-1": "Fired on updating of a course", "39-1": "Fired on updating of a subscription", "32-1": "Fired on deletion of a Federation", "35-1": "Fired on deletion of a course", "40-1": "Fired on deletion of a subscription", "36-1": "Fired on rankings being run", "37-1": "Fired on rankings being published", "41-0": "[timing.store](https://developers.triathlon.org/docs/live-timing)", "41-1": "Fired for a new live timing message" }, "cols": 2, "rows": 42 } [/block] [block:callout] { "type": "info", "title": "Webhook Integration Services", "body": "Using services such as [Zapier](http://zapier.com) 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." } [/block] [block:api-header] { "type": "basic", "title": "Retries" } [/block] 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). [block:callout] { "type": "warning", "title": "3xx responses will not be followed and will not be retried, only 4xx and 5xx responses" } [/block] [block:parameters] { "data": { "0-0": "1", "h-0": "Retry Count", "h-1": "Next Retry", "h-2": "Total Seconds Elasped", "9-0": "10", "1-0": "2", "2-0": "3", "3-0": "4", "4-0": "5", "5-0": "6", "6-0": "7", "7-0": "8", "8-0": "9", "0-1": "61", "0-2": "61", "1-1": "76", "2-1": "141", "3-1": "361", "4-1": "685", "5-1": "1,356", "6-1": "2,461", "7-1": "4,156", "8-1": "6,621", "9-1": "10,060", "1-2": "137", "2-2": "217", "3-2": "457", "4-2": "1,001", "5-2": "2,041", "6-2": "3,817", "7-2": "6,617", "8-2": "10,777", "9-2": "16,681" }, "cols": 3, "rows": 10 } [/block] [block:api-header] { "type": "basic", "title": "Authentication" } [/block] 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 [block:api-header] { "type": "basic", "title": "Debugging" } [/block] 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](https://developers.triathlon.org/docs/create-an-athlete). To debug webhooks consider using a service such as [RequestBin](http://requestb.in/) to ensure you are receiving the response and then edit your subscription to match your production URL.