{"_id":"57d1b5ea5284c90e00cc067f","project":"55773a5ba042551900b002cb","user":{"_id":"546d17e2eb9cfd1400dd4529","username":"","name":"World Triathlon"},"__v":0,"initVersion":{"_id":"55773a5ba042551900b002ce","version":"1"},"createdAt":"2016-09-08T19:03:06.904Z","changelog":[],"body":"The [Subscriptions API](https://developers.triathlon.org/docs/subscriptions-api-overview) is a powerful tool for being notified of changes in resources on the Triathlon API platform. Whilst the full functionality is currently in *closed beta* we have opened up subscriptions to the [Rankings API](https://developers.triathlon.org/docs/rankings-api-overview) via the [app management portal](https://apps.api.triathlon.org/).\n\nThe Subscriptions API implements [webhooks](https://en.wikipedia.org/wiki/Webhook) to notify any subscribers of changes on the platform, which in the case of the Rankings API are either the rankings being [run](https://developers.triathlon.org/docs/run-ranking) or [published](https://developers.triathlon.org/docs/publish-ranking). Simply put, when a ranking is published a JSON payload is sent to a subscriber URL containing a message that indicates which ranking was run and any other relevant meta data. For example when the female ITU World Series Rankings are published the following message would be sent.\n\n```json\n{  \n   \"subscription\":\"ranking.publish\",\n   \"payload\":{  \n      \"id\":16,\n      \"category\":\"Elite Women\",\n      \"last_updated\":\"2016-09-08 17:49:23\",\n      \"type\":\"World Triathlon Series\",\n      \"region_id\":null\n   }\n}\n```\n\nBased on this message the recipient can make changes on their own systems. For example making a [subsequent request for the full ranking information](https://developers.triathlon.org/docs/ranking-detail) such that the user always has the latest ranking information available. As the notification happens in real-time it saves the user from continuously checking the rankings to know if they have the latest ranking information as they will be notified of any changes as they occur.\n\nWhilst currently only the Rankings API is supported with the `rankings.publish` and `rankings.run` methods we will include all data sources in due course. By incorporating these other subscriptions example use cases include:\n\n* A press release could be sent on the publishing of a new article using `article.publish`\n* A National Federation could add/update information in a local database once profile information has been updated on Triathlon.org using `athlete.store` or `athlete.update`\n* A race organizer could be notified of entries as they occur and any changes to entries using `entry.store`, `entry.update` or `entry.destroy`\n\nThe beauty of webhooks is in their flexibility and they can be used to trigger a huge variety of existing services such as the [Zapier](hhttps://zapier.com/) service. For the remainder of this article we will detail a process of using the Subscription API to be notified via text message (using [Twilio](https://www.twilio.com/)) whenever the female World Triathlon Series rankings are published. Clearly this approach may be applied to more practical use-cases such as updating an internal database when rankings are published thus ensuring that the most up-to-date information is always available.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating a Subscription\"\n}\n[/block]\nTo create a subscription log into the [API management portal](https://apps.api.triathlon.org/) and choose `Register a Subscription` and you will be displayed the following form: (it is also possible to [create subscriptions via the API directly](https://developers.triathlon.org/docs/create-subscription)).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8da07f6-subscription_form.png\",\n        \"subscription_form.png\",\n        1175,\n        692,\n        \"#e4ecef\"\n      ],\n      \"caption\": \"Subscription Registration Form\"\n    }\n  ]\n}\n[/block]\nThe form contains options for customizing the notification sent:\n\n* **Name**: A name to identify the subscription\n* **URL**: The webhook URL to send the generated messages\n* **Token**: An optional secret token which is included in all outgoing requests such that you can be assured that the message was sent from the Triathlon API\n* **Email Notifications**: Whether you wish to receive an email notification for any failed webhook notifications (note that the Subscriptions API uses an [exponential back-off style retry policy](https://developers.triathlon.org/docs/subscriptions-api-overview#retries) such that several delivery attempts are made before a failure would occur)\n* **Subscriptions**: The subscription(s) to which we wish to subscribe\n\nIn our case we will generate a URL from the [Zapier](https://zapier.com) service which will receive our webhook request. Once registered and signed in to Zapier we will create a new Zap with our _Trigger App_ as a `Catch Hook` from the Zapier Webhooks app which will give us a custom URL to use to add to the Subscription API form (you may leave all other Zapier options as their defaults). Once we have the URL to post to we submit the Subscription API form using a descriptive name and subscribing to the `ranking.publish` notification. Now whenever any ranking is published a webhook will be sent to our new Zapier app.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the Webhook as a Trigger\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Zapier has over 500 integrations with other services that you may substitute for the example Twilio application demonstrated\"\n}\n[/block]\nCurrently we are receiving all `ranking.publish` notifications whereas we are only interested in the women's rankings of the ITU World Triathlon Series. By using the [Rankings Listing](https://developers.triathlon.org/docs/rankings-listing) method of the Triathlon API or by [consulting this table](https://developers.triathlon.org/docs/rankings-api-overview#available-rankings) we can see that the `ranking_id` that we are interested in is **16**. In order to restrict when notifications trigger our SMS message we will apply a _Filter_ step in Zapier to only continue if the Payload ID is equal to 16 (see the payload object in the same message above).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a630ada-zapier-filter.png\",\n        \"zapier-filter.png\",\n        775,\n        391,\n        \"#e1e7e9\"\n      ],\n      \"caption\": \"Using a filter in Zapier to only send notifications that match our criteria\"\n    }\n  ]\n}\n[/block]\nFinally, we will implement the Twilio integration in Zapier to actually send the message (you would need to be a Twilio subscriber and authenticate the service in Zapier). We will use the _Send SMS_ action and customise the message body so that the name of the ranking is displayed in the resulting SMS.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b92bcba-twilio-message.png\",\n        \"twilio-message.png\",\n        778,\n        158,\n        \"#e3e4e7\"\n      ],\n      \"caption\": \"Configuring the message that will be sent when rankings are published\"\n    }\n  ]\n}\n[/block]\n```Note that it would also be possible to add a further step to retrieve the full rankings using the `ranking_id` and then for example save the results in a Google Sheet integration.```\n\nNow when the women's ITU World Triathlon Series rankings are published we receive the following message via SMS.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0bc266e-sms-message.png\",\n        \"sms-message.png\",\n        1117,\n        317,\n        \"#ecebec\"\n      ],\n      \"caption\": \"Resulting SMS sent on any publishing of the rankings\"\n    }\n  ]\n}\n[/block]\nYou can discuss this article or using the Subscription API on our [Slack channel](http://slack.developers.triathlon.org/).","slug":"working-with-the-subscriptions-api","title":"Working with the Subscriptions API"}

Working with the Subscriptions API


The [Subscriptions API](https://developers.triathlon.org/docs/subscriptions-api-overview) is a powerful tool for being notified of changes in resources on the Triathlon API platform. Whilst the full functionality is currently in *closed beta* we have opened up subscriptions to the [Rankings API](https://developers.triathlon.org/docs/rankings-api-overview) via the [app management portal](https://apps.api.triathlon.org/). The Subscriptions API implements [webhooks](https://en.wikipedia.org/wiki/Webhook) to notify any subscribers of changes on the platform, which in the case of the Rankings API are either the rankings being [run](https://developers.triathlon.org/docs/run-ranking) or [published](https://developers.triathlon.org/docs/publish-ranking). Simply put, when a ranking is published a JSON payload is sent to a subscriber URL containing a message that indicates which ranking was run and any other relevant meta data. For example when the female ITU World Series Rankings are published the following message would be sent. ```json { "subscription":"ranking.publish", "payload":{ "id":16, "category":"Elite Women", "last_updated":"2016-09-08 17:49:23", "type":"World Triathlon Series", "region_id":null } } ``` Based on this message the recipient can make changes on their own systems. For example making a [subsequent request for the full ranking information](https://developers.triathlon.org/docs/ranking-detail) such that the user always has the latest ranking information available. As the notification happens in real-time it saves the user from continuously checking the rankings to know if they have the latest ranking information as they will be notified of any changes as they occur. Whilst currently only the Rankings API is supported with the `rankings.publish` and `rankings.run` methods we will include all data sources in due course. By incorporating these other subscriptions example use cases include: * A press release could be sent on the publishing of a new article using `article.publish` * A National Federation could add/update information in a local database once profile information has been updated on Triathlon.org using `athlete.store` or `athlete.update` * A race organizer could be notified of entries as they occur and any changes to entries using `entry.store`, `entry.update` or `entry.destroy` The beauty of webhooks is in their flexibility and they can be used to trigger a huge variety of existing services such as the [Zapier](hhttps://zapier.com/) service. For the remainder of this article we will detail a process of using the Subscription API to be notified via text message (using [Twilio](https://www.twilio.com/)) whenever the female World Triathlon Series rankings are published. Clearly this approach may be applied to more practical use-cases such as updating an internal database when rankings are published thus ensuring that the most up-to-date information is always available. [block:api-header] { "type": "basic", "title": "Creating a Subscription" } [/block] To create a subscription log into the [API management portal](https://apps.api.triathlon.org/) and choose `Register a Subscription` and you will be displayed the following form: (it is also possible to [create subscriptions via the API directly](https://developers.triathlon.org/docs/create-subscription)). [block:image] { "images": [ { "image": [ "https://files.readme.io/8da07f6-subscription_form.png", "subscription_form.png", 1175, 692, "#e4ecef" ], "caption": "Subscription Registration Form" } ] } [/block] The form contains options for customizing the notification sent: * **Name**: A name to identify the subscription * **URL**: The webhook URL to send the generated messages * **Token**: An optional secret token which is included in all outgoing requests such that you can be assured that the message was sent from the Triathlon API * **Email Notifications**: Whether you wish to receive an email notification for any failed webhook notifications (note that the Subscriptions API uses an [exponential back-off style retry policy](https://developers.triathlon.org/docs/subscriptions-api-overview#retries) such that several delivery attempts are made before a failure would occur) * **Subscriptions**: The subscription(s) to which we wish to subscribe In our case we will generate a URL from the [Zapier](https://zapier.com) service which will receive our webhook request. Once registered and signed in to Zapier we will create a new Zap with our _Trigger App_ as a `Catch Hook` from the Zapier Webhooks app which will give us a custom URL to use to add to the Subscription API form (you may leave all other Zapier options as their defaults). Once we have the URL to post to we submit the Subscription API form using a descriptive name and subscribing to the `ranking.publish` notification. Now whenever any ranking is published a webhook will be sent to our new Zapier app. [block:api-header] { "type": "basic", "title": "Using the Webhook as a Trigger" } [/block] [block:callout] { "type": "warning", "title": "Zapier has over 500 integrations with other services that you may substitute for the example Twilio application demonstrated" } [/block] Currently we are receiving all `ranking.publish` notifications whereas we are only interested in the women's rankings of the ITU World Triathlon Series. By using the [Rankings Listing](https://developers.triathlon.org/docs/rankings-listing) method of the Triathlon API or by [consulting this table](https://developers.triathlon.org/docs/rankings-api-overview#available-rankings) we can see that the `ranking_id` that we are interested in is **16**. In order to restrict when notifications trigger our SMS message we will apply a _Filter_ step in Zapier to only continue if the Payload ID is equal to 16 (see the payload object in the same message above). [block:image] { "images": [ { "image": [ "https://files.readme.io/a630ada-zapier-filter.png", "zapier-filter.png", 775, 391, "#e1e7e9" ], "caption": "Using a filter in Zapier to only send notifications that match our criteria" } ] } [/block] Finally, we will implement the Twilio integration in Zapier to actually send the message (you would need to be a Twilio subscriber and authenticate the service in Zapier). We will use the _Send SMS_ action and customise the message body so that the name of the ranking is displayed in the resulting SMS. [block:image] { "images": [ { "image": [ "https://files.readme.io/b92bcba-twilio-message.png", "twilio-message.png", 778, 158, "#e3e4e7" ], "caption": "Configuring the message that will be sent when rankings are published" } ] } [/block] ```Note that it would also be possible to add a further step to retrieve the full rankings using the `ranking_id` and then for example save the results in a Google Sheet integration.``` Now when the women's ITU World Triathlon Series rankings are published we receive the following message via SMS. [block:image] { "images": [ { "image": [ "https://files.readme.io/0bc266e-sms-message.png", "sms-message.png", 1117, 317, "#ecebec" ], "caption": "Resulting SMS sent on any publishing of the rankings" } ] } [/block] You can discuss this article or using the Subscription API on our [Slack channel](http://slack.developers.triathlon.org/).