Share via

Service hook subscriptions

  • Article

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 1.0

A service hooks subscription defines the action to perform on a consumer service when an event occurs in a project. For example, a subscription can cause a card to be created on a Trello board when a work item is created.

If you haven't already, look at the information on getting started with these APIs.

Get a list of subscriptions

Sample request

GET https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/?api-version=1.0

Sample response

{
    "count": 12,
    "value": [
        {
        "id": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "publisherId": "tfs",
        "eventType": "build.complete",
        "resourceVersion": null,
        "eventDescription": "Build CustomerAddressModule, Status Succeeded",
        "consumerId": "myGet",
        "consumerActionId": "publishPackage",
        "actionDescription": "Feed: fabrikam-package",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-20T19:47:15.247Z",
        "modifiedBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "modifiedDate": "2014-05-20T19:47:15.247Z",
        "publisherInputs": {
            "buildStatus": "Succeeded",
            "definitionName": "CustomerAddressModule",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "e15ed970-8b92-4b71-8ec2-f99b5db5e34d"
        },
        "consumerInputs": {
            "feedId": "fabrikam-package",
            "packageSourceId": "ef1a74fb-53e3-46b8-9d8f-03a38a9c7b78"
        }
        },
        {
        "id": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
        "publisherId": "tfs",
        "eventType": "build.complete",
        "resourceVersion": null,
        "eventDescription": "Any completed build",
        "consumerId": "jenkins",
        "consumerActionId": "triggerGenericBuild",
        "actionDescription": "Server: ossbinjenkins.cloudapp.net, Build: GitBuild",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-22T21:40:27.12Z",
        "modifiedBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "modifiedDate": "2014-05-22T21:40:27.12Z",
        "publisherInputs": {
            "buildStatus": "",
            "definitionName": "",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "tfsSubscriptionId": "fe4c65f7-e421-4cee-b4d9-055b7239a79c"
        },
        "consumerInputs": {
            "buildName": "GitBuild",
            "serverBaseUrl": "http://ossbinjenkins.cloudapp.net:8080/",
            "username": "ossadmin",
            "password": "********"
        }
        },
        {
        "id": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
        "status": "disabledBySystem",
        "publisherId": "tfs",
        "eventType": "build.complete",
        "resourceVersion": "1.0-preview.1",
        "eventDescription": "",
        "consumerId": "webHooks",
        "consumerActionId": "httpRequest",
        "actionDescription": "",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-02T19:13:45.767Z",
        "modifiedBy": {
            "id": "31394b6e-666e-4ca8-8f92-4cc712caf9e2"
        },
        "modifiedDate": "2014-06-09T14:41:54.653Z",
        "publisherInputs": {
            "buildStatus": "",
            "definitionName": "MyWebSite CI",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "9e1cdeec-05f9-4ca0-9462-fde704958419"
        },
        "consumerInputs": {
            "url": "http://requestb.in/stkb4jst"
        }
        },
        {
        "id": "dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
        "status": "onProbation",
        "publisherId": "tfs",
        "eventType": "build.complete",
        "resourceVersion": "1.0-preview.1",
        "eventDescription": "Any completed build.",
        "consumerId": "webHooks",
        "consumerActionId": "httpRequest",
        "actionDescription": "To host requestb.in",
        "probationRetries": 6,
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-06-11T15:14:09.27Z",
        "modifiedBy": {
            "id": "31394b6e-666e-4ca8-8f92-4cc712caf9e2"
        },
        "modifiedDate": "2014-10-07T22:19:27.41Z",
        "publisherInputs": {
            "buildStatus": "",
            "definitionName": "",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "ed56d972-3668-42c3-9a9f-82547ae2c391"
        },
        "consumerInputs": {
            "url": "http://requestb.in/1c6c3bh1"
        }
        },
        {
        "id": "eeee4efe-ff5f-aa6a-bb7b-cccccc8c8c8c",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/eeee4efe-ff5f-aa6a-bb7b-cccccc8c8c8c",
        "status": "onProbation",
        "publisherId": "tfs",
        "eventType": "git.push",
        "resourceVersion": "1.0-preview.1",
        "eventDescription": "",
        "consumerId": "webHooks",
        "consumerActionId": "httpRequest",
        "actionDescription": "",
        "probationRetries": 2,
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-02T19:14:03.27Z",
        "modifiedBy": {
            "id": "31394b6e-666e-4ca8-8f92-4cc712caf9e2"
        },
        "modifiedDate": "2014-06-30T17:48:52.017Z",
        "publisherInputs": {
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "390db3c8-616d-417a-9b44-725f415a4409"
        },
        "consumerInputs": {
            "url": "http://requestb.in/stkb4jst"
        }
        },
        {
        "id": "ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d",
        "status": "onProbation",
        "publisherId": "tfs",
        "eventType": "git.push",
        "resourceVersion": null,
        "eventDescription": "Any branch on any repository",
        "consumerId": "jenkins",
        "consumerActionId": "triggerGenericBuild",
        "actionDescription": "Server: fabrikam-fiber-inc.ci.cloudbees.com, Build: MyBuild",
        "probationRetries": 1,
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-06-09T21:02:19.82Z",
        "modifiedBy": {
            "id": "31394b6e-666e-4ca8-8f92-4cc712caf9e2"
        },
        "modifiedDate": "2014-06-30T18:11:06.19Z",
        "publisherInputs": {
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "fb307bd5-cf4c-41f1-b26f-077b417627ba"
        },
        "consumerInputs": {
            "buildName": "MyBuild",
            "buildParameterized": "False",
            "serverBaseUrl": "https://fabrikam-fiber-inc.ci.cloudbees.com",
            "username": "[email protected]",
            "password": "********"
        }
        },
        {
        "id": "aaaa6a6a-bb7b-cc8c-dd9d-eeeeee0e0e0e",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/aaaa6a6a-bb7b-cc8c-dd9d-eeeeee0e0e0e",
        "publisherId": "tfs",
        "eventType": "git.push",
        "resourceVersion": null,
        "eventDescription": "",
        "consumerId": "trello",
        "consumerActionId": "createCard",
        "actionDescription": "",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-04-16T21:40:46.5Z",
        "modifiedBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "modifiedDate": "2014-04-16T21:40:46.5Z",
        "publisherInputs": {
            "branch": "master",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "repository": "278d5cd2-584d-4b63-824a-2ba458937249",
            "tfsSubscriptionId": "416c686b-de28-4f2b-bfc2-33c9f5392fed"
        },
        "consumerInputs": {
            "addToTop": "True",
            "boardId": "531e1ae7f8f090f93829e83c",
            "listId": "531e1babb29c372b47783433",
            "userToken": "********"
        }
        },
        {
        "id": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "publisherId": "tfs",
        "eventType": "tfvc.checkin",
        "resourceVersion": "1.0-preview.1",
        "eventDescription": "Path $/Fabrikam-Fiber-TFVC",
        "consumerId": "webHooks",
        "consumerActionId": "httpRequest",
        "actionDescription": "To host requestb.in",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-12T22:38:28.837Z",
        "modifiedBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "modifiedDate": "2014-05-12T22:38:28.837Z",
        "publisherInputs": {
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "path": "$/Fabrikam-Fiber-TFVC",
            "projectId": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "tfsSubscriptionId": "6bf0f776-1e2e-45fc-90ee-ca8b00ac1c85"
        },
        "consumerInputs": {
            "url": "http://requestb.in/z1iwd9z1"
        }
        },
        {
        "id": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
        "publisherId": "tfs",
        "eventType": "workitem.commented",
        "resourceVersion": null,
        "eventDescription": "Any work item",
        "consumerId": "zendesk",
        "consumerActionId": "createPrivateComment",
        "actionDescription": "Account name: FabrikamFiber",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-20T20:29:49.52Z",
        "modifiedBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "modifiedDate": "2014-05-20T20:29:49.52Z",
        "publisherInputs": {
            "areaPath": "",
            "commentPattern": "Zendesk:",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "tfsSubscriptionId": "e1d1041d-4722-4240-8e0f-8123c90e4570",
            "workItemType": ""
        },
        "consumerInputs": {
            "accountName": "FabrikamFiber",
            "username": "[email protected]",
            "apiToken": "********"
        }
        },
        {
        "id": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
        "publisherId": "tfs",
        "eventType": "workitem.commented",
        "resourceVersion": "1.0-preview.1",
        "eventDescription": "",
        "consumerId": "webHooks",
        "consumerActionId": "httpRequest",
        "actionDescription": "",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-02T19:14:35.39Z",
        "modifiedBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "modifiedDate": "2014-05-02T19:14:35.39Z",
        "publisherInputs": {
            "areaPath": "",
            "commentPattern": "My",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "68c12bdc-ba05-4faa-8505-9612987d2ff0",
            "workItemType": ""
        },
        "consumerInputs": {
            "url": "http://requestb.in/stkb4jst"
        }
        },
        {
        "id": "dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
        "status": "disabledBySystem",
        "publisherId": "tfs",
        "eventType": "workitem.created",
        "resourceVersion": "1.0-preview.1",
        "eventDescription": "",
        "consumerId": "webHooks",
        "consumerActionId": "httpRequest",
        "actionDescription": "",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-02T19:14:20.23Z",
        "modifiedBy": {
            "id": "31394b6e-666e-4ca8-8f92-4cc712caf9e2"
        },
        "modifiedDate": "2014-09-30T20:57:27.783Z",
        "publisherInputs": {
            "areaPath": "",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "4ee183da-f941-4d82-8139-5d1a5c0b6dcc",
            "workItemType": ""
        },
        "consumerInputs": {
            "url": "http://requestb.in/stkb4jst"
        }
        },
        {
        "id": "eeee4efe-ff5f-aa6a-bb7b-cccccc8c8c8c",
        "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/eeee4efe-ff5f-aa6a-bb7b-cccccc8c8c8c",
        "status": "disabledBySystem",
        "publisherId": "tfs",
        "eventType": "workitem.updated",
        "resourceVersion": "1.0-preview.1",
        "eventDescription": "",
        "consumerId": "webHooks",
        "consumerActionId": "httpRequest",
        "actionDescription": "",
        "createdBy": {
            "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
        },
        "createdDate": "2014-05-02T19:14:46.243Z",
        "modifiedBy": {
            "id": "31394b6e-666e-4ca8-8f92-4cc712caf9e2"
        },
        "modifiedDate": "2014-08-04T22:24:21.067Z",
        "publisherInputs": {
            "areaPath": "",
            "changedFields": "",
            "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
            "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "tfsSubscriptionId": "da2238b1-724d-4757-97fa-9cae9388cbdc",
            "workItemType": ""
        },
        "consumerInputs": {
            "url": "http://requestb.in/stkb4jst"
        }
        }
    ]
}

Get a subscription

Sample request

GET https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e?api-version=1.0

Sample response

{
  "id": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "publisherId": "tfs",
  "eventType": "build.complete",
  "resourceVersion": null,
  "eventDescription": "Build CustomerAddressModule, Status Succeeded",
  "consumerId": "myGet",
  "consumerActionId": "publishPackage",
  "actionDescription": "Feed: fabrikam-package",
  "createdBy": {
    "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
  },
  "createdDate": "2014-05-20T19:47:15.247Z",
  "modifiedBy": {
    "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
  },
  "modifiedDate": "2014-05-20T19:47:15.247Z",
  "publisherInputs": {
    "buildStatus": "Succeeded",
    "definitionName": "CustomerAddressModule",
    "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
    "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
    "tfsSubscriptionId": "e15ed970-8b92-4b71-8ec2-f99b5db5e34d"
  },
  "consumerInputs": {
    "feedId": "fabrikam-package",
    "packageSourceId": "ef1a74fb-53e3-46b8-9d8f-03a38a9c7b78"
  }
}

Create a subscription

Sample request

POST https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions?api-version=1.0

{
  "publisherId": "tfs",
  "eventType": "build.complete",
  "resourceVersion": "1.0-preview.1",
  "consumerId": "webHooks",
  "consumerActionId": "httpRequest",
  "publisherInputs": {
    "buildStatus": "Failed",
    "definitionName": "MyWebSite CI",
    "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c"
  },
  "consumerInputs": {
    "url": "https://myservice/myhookeventreceiver"
  }
}

Sample response

{
  "id": "ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d",
  "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d",
  "publisherId": "tfs",
  "eventType": "build.complete",
  "resourceVersion": "1.0-preview.1",
  "eventDescription": "Build MyWebSite CI, status Failed",
  "consumerId": "webHooks",
  "consumerActionId": "httpRequest",
  "actionDescription": "To host myservice",
  "createdBy": {
    "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
  },
  "createdDate": "2014-10-27T15:37:24.873Z",
  "modifiedBy": {
    "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
  },
  "modifiedDate": "2014-10-27T15:37:24.873Z",
  "publisherInputs": {
    "buildStatus": "Failed",
    "definitionName": "MyWebSite CI",
    "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
    "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
    "tfsSubscriptionId": "3e8b33e7-426d-4c92-9bf9-58e163dd7dd5"
  },
  "consumerInputs": {
    "url": "https://myservice/myhookeventreceiver"
  }
}

Update a subscription

Sample request

PUT https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d?api-version=1.0

{
  "publisherId": "tfs",
  "eventType": "build.complete",
  "resourceVersion": "1.0-preview.1",
  "consumerId": "webHooks",
  "consumerActionId": "httpRequest",
  "publisherInputs": {
    "buildStatus": "Failed",
    "definitionName": "MyWebSite CI",
    "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c"
  },
  "consumerInputs": {
    "url": "https://myservice/newreceiver"
  }
}

Sample response

{
  "id": "ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d",
  "url": "https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d",
  "publisherId": "tfs",
  "eventType": "build.complete",
  "resourceVersion": "1.0-preview.1",
  "eventDescription": "Build MyWebSite CI, status Failed",
  "consumerId": "webHooks",
  "consumerActionId": "httpRequest",
  "actionDescription": "To host myservice",
  "createdBy": {
    "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
  },
  "createdDate": "2014-10-27T15:37:24.873Z",
  "modifiedBy": {
    "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
  },
  "modifiedDate": "2014-10-27T15:37:26.23Z",
  "publisherInputs": {
    "buildStatus": "Failed",
    "definitionName": "MyWebSite CI",
    "hostId": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
    "projectId": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
    "tfsSubscriptionId": "3e8b33e7-426d-4c92-9bf9-58e163dd7dd5"
  },
  "consumerInputs": {
    "url": "https://myservice/newreceiver"
  }
}

Delete a subscription

Sample request

DELETE https://mytfsserver/DefaultCollection/_apis/hooks/subscriptions/ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d?api-version=1.0