This article is intended to help developers port existing software that uses a deprecated version of the “webhook” integration POST-body format. Please see the documentation for activity webhooks and the reference for the v5 activity resource structure. The v5 format will be the only available version, and there are currently no plans for a newer version.
The older v3 version of the Tracker API will be removed on December 31, 2017. Applications using the v3 API will no longer work after this date, and all webhooks configured to use v3-format data will be removed.
If your projects are using webhooks with data format based on the v5 API already, you won’t be affected.
Changing an existing webhook from v3 to v5 in Tracker
- Click Settings in your project, then choose Webhooks in the sidebar.
- Click on the dropdown to the right of the URL and change the selection to v5.
Changing your software to handle a v5-format webhook
Selecting “v3” or “v5” for the format of Webhook POSTs from Tracker affects only the content of the HTTP request’s body. All other aspects of webhooks from Tracker remain the same. Given this, the biggest part of adapting a system expecting webhooks formatted according to v3 will be changing from parsing the old XML-based format to parsing the larger, more expressive JSON content.
To ensure forward compatibility with updates made to Tracker that do not require an API version change, your code should
- use a fully featured and standard-compliant JSON parser to process API responses (for an introduction, see json.org, and for reference see ECMA-404/RFC7159); and
- be capable of ignoring hash (object) keys that you don’t use.
A number of v3 client applications were written to parse webhook bodies with templates or regular expressions, which made them sensitive to the introduction of new elements or attributes and to changes in the order in which data was included. We kept the format of v3 webhook bodies consistent enough over time that the majority of such clients had long lifespans despite their brittleness. The same frozen formatting is not present in v5.
For example, Pivotal Tracker added the item
blockers to the response provided from
stories endpoints after the v5 API was published, without increasing the API version number beyond 5. See the API Versioning section of the API documentation.
The format of webhook POST bodies is detailed in the v5 reference documentation for the
activity resource. Note that because individual webhooks are not requested by an API client, they use all of the “default” formatting of the
activity resource, while API requests that produce
activity items in their response can control the formatting/content of the
activity items with the
fields request parameter.
The following gives a mapping between the individual fields provided in a v3-format webhook POST body and the location of equivalent data within the v5-format structure.
This comparison highlights the two biggest change between the v3 and v5 activity formats:
- the replacement of the single
storiesarray with a number of more specific polymorphic arrays; and
- the separation of subresources from the resource items that contain/reference them.
In v5, webhooks (and activity if you GET it from a v5 API endpoint) are produced for a much broader set of update operations, including not only ones that affect stories, but also epics and the overall project. The
primary_resources array now indicates the resources stored in Tracker that were the intended target of the user’s change, and each entry in the array contains information only to identify the resource (e.g.,
story_type in the case where the resource is a
story). In the case of a simple operation like creating or updating a story, the v3
stories array would contain only a single
story item, and the v5 activity for that same operation will also have only a single entry in the
primary_resources array, identifying the same story. In the case where a number of stories are moved, the v3
stories and v5
primary_resources arrays will continue to correlate.
However, unlike v3, the v5 activity format does not put the information identifying what was intended to be changed in the same place as the actual list of values changed. In v5, changes to individual resource attributes are indicated by the
changes array, for both the item(s) listed in
primary_resouces and any other resources that were updated simultaneously as side effects of the intended change. You’ll notice in the example above that subscripts into the
changes array are indicated with “x” and “y.” For a v5-format webhook, when the client software wants to process/present information about a specific resource’s changes, it is required to scan the
changes array until it finds an item that has the
kind values that match that resource. In the example above, “x” represents the
changes array subscript that corresponds to the (hypothetical) first entry in the corresponding v3
stories array, and “y” represents the
changes subscript for an individual comment attached to that same story (
In v3-format activity, only the new values of the changed story’s attributes were provided in the activity structure. In a v5-format activity item, new values are located in the
new_values hash and the values that were present before the change represented by the activity are located in the
old_values hash of the same
changes array entry.
For more information on using the new information present in v5-format webhook POST bodies, see the introductory description of interpreting an activity item in the v5 API documentation.