Create a custom consumer for service hooks

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Use service hooks to notify external systems about events in your Azure DevOps project. A custom consumer extension sends an HTTP POST to an endpoint you configure when specific events occur.

This article shows how to build an extension that implements a sample consumer service. The example consumer:

• Listens for three Git events: code pushed, pull request created, and pull request updated
• Sends an HTTP POST with the event payload to a configurable endpoint URL

For the complete source, see the extension sample GitHub repo. For all available event types, see Service hook event types.

How service hooks work

Service hooks have three components:

• Publishers emit events, such as "code pushed" or "pull request created."
• Subscriptions match specific events to actions.
• Consumers define the actions to run, such as sending an HTTP POST.

In this article, the extension implements a custom consumer. When a matching event occurs, the consumer sends an HTTP POST with the event payload to the endpoint URL configured in the subscription.

Create the extension

1. Set up the project

Create your extension project. For instructions, see Develop a web extension.

2. Add the consumer contribution

Add the consumer contribution to your manifest file (vss-extension.json). The following example shows a complete manifest with a service hook consumer:

{
    "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"
                        }
                    }
                ]
            }
        }
    ]
}

The contributions array is the key section. Each contribution defines:

• Type: ms.vss-servicehooks.consumer — registers a consumer service
• Target: ms.vss-servicehooks.consumers — the consumer services collection
• Properties: Consumer configuration, including inputs and actions (see property reference)

3. Package, publish, and test

Package and publish the extension to your Azure DevOps organization. Then create a service hook subscription that uses your custom consumer to verify it works.

Property reference

Consumer properties

Action properties

Each action in the actions array has the following properties:

Next step

Related content

• Service hook consumers
• Available services for service hooks
• Create a service hook subscription programmatically
• Extension example GitHub repository
• List of event types