Service hooks in Team Services

Last Update: 12/5/2016

Service hooks enable you to perform tasks on other services when events happen in your Visual Studio Team Services projects. For example, create a card in Trello when a work item is created or send a push notification to your team's mobile devices when a build fails. Service hooks can also be used in custom apps and services as a more efficient way to drive activities when events happen in your projects.

How service hooks work

Service hook publishers define a set of events. Subscriptions listen for the events and define actions to take based on the event. Subscriptions also target consumers, which are external services that can perform their own actions, when an event occurs.

Service Hooks Diagram

Tutorial Overview - Custom Consumer Service

This tutorial walks through developing an extension that implements a sample consumer service that includes:

  • Supported events that trigger actions to be taken
    • Code pushed
    • Pull request created
    • Pull request updated
  • Supported actions to take when events occur
    • Perform action

Note: This tutorial will refer to the home directory for your project as "home".

Sample Consumer Service

Create the extension

Add an icon

Add a square image in the images folder that identifies your extension. It will displayed in the Marketplace, and when someone installs your extension. You don't need to do this for your extension to work, but below is a sample image you can use along with how it will look with the extension.

NOTE: Name the image logo.png, or remove the "icons" sections from the manifest file if you wish to skip this step.

Create the manifest file and populate it

The manifest file defines both your extension and the consumer service.

Create a json file (vss-extension.json, for example) in the home directory of your extension with the following contents:

{
    "manifestVersion": 1,
    "id": "samples-service-hooks-consumer",
    "version": "0.1.2",
    "name": "Service Hooks Sample",
    "description": "A simple extension that demonstrates how to contribute a consumer service into service hooks.",
    "publisher": "fabrikam",
    "public": false,
    "icons": {
        "default": "images/logo.png"
    },
    "scopes": [],
    "files": [
        {
            "path": "images",
            "addressable": true
        }
    ],
    "content": {
        "details": {
            "path": "readme.md"
        }
    },
    "categories": [
        "Developer samples"
    ],
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "contributions": [
        {
            "id": "consumer",
            "type": "ms.vss-servicehooks.consumer",
            "targets": [
                "ms.vss-servicehooks.consumers"
            ],
            "properties": {
                "id": "consumer",
                "name": "Sample Consumer",
                "description": "Sample consumer service",
                "informationUrl": "https://aka.ms/vsoextensions",
                "inputDescriptors": [
                    {
                        "id": "url",
                        "isRequired": true,
                        "name": "URL",
                        "description": "URL to post event payload to",
                        "inputMode": "textbox"
                    }
                ],
                "actions": [
                    {
                        "id": "performAction",
                        "name": "Perform action",
                        "description": "Posts a standard event payload",
                        "supportedEventTypes": [
                            "git.push",
                            "git.pullrequest.created",
                            "git.pullrequest.updated"
                        ],
                        "publishEvent": {
                            "url": "{{{url}}}",
                            "resourceDetailsToSend": "all",
                            "messagesToSend": "all",
                            "detailedMessagesToSend": "all"
                        }
                    }
                ]
            }
        }
    ]
}

Note: You will need to update the publisher property.

The icons stanza specifies the path to your extension's icon in your manifest.

The contributions stanza adds your contribution - the consumer service - to your extension manifest.

For each contribution in your extension, the manifest defines

  • the type of contribution - consumer service (ms.vss-servicehooks.consumer) in this case,
  • the contribution target - consumer services (ms.vss-servicehooks.consumers) in this case,
  • and the properties that are specific to each type of contribution. For a consumer service we have:
Property Description
id unique id for your consumer service
name name of the consumer service
description describes your consumer service
informationUrl where more info can be found about your extension
inputDescriptors inputs to be used by users that are creating subscriptions with the consumer service
actions describes the actions to take and which events trigger them

Package, Publish, and Install

Now that you've written your extension, the next steps are to Package, Publish, and Install your extension. You can also check out the documentation for Testing and Debugging your extension.