Migrating webhooks to API v5

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

If you are an owner of the project, an account admin, or the owner of the account the project is in, you can update your existing v3 webhooks to v5.

  1. Click Settings in your project, then choose Webhooks in the sidebar.
  2. Click on the dropdown to the right of the URL and change the selection to v5.

Change your v3 project webhook from v5 using the Webhooks page in the Settings tab.

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

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

v3 v5
id guid
version project_version
event_type kind
occurred_at occurred_at
author performed_by.name
project_id project.id
description message
stories/story/id primary_resources[0].id
stories/story/url primary_resources[0].url
stories/story/name primary_resources[0].name
stories/story/story_type primary_resources[0].story_type
stories/story/id changes[x].id
stories/story/story_type changes[x].new_values.story_type
stories/story/estimate changes[x].new_values.estimate
stories/story/labels changes[x].new_values.labels
stories/story/accepted_at changes[x].new_values.accepted_at
stories/story/current_state changes[x].new_values.current_state
stories/story/requested_by changes[x].new_values.requested_by_id
stories/story/notes/note/text changes[y].new_values.text

This comparison highlights the two biggest change between the v3 and v5 activity formats:

  1. the replacement of the single stories array with a number of more specific polymorphic arrays; and
  2. 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., id, name, url, and 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 id and 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 ("kind":"comment").

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.

Webhook format v5