Create a custom consumer for service hooks

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

Use service hooks to notify non-Microsoft systems about events that occur in your project. A custom consumer sends an HTTP message to the endpoint defined in your extension's manifest.

This article walks through developing an extension that implements a sample consumer service, which includes the following events and actions.

• Supported events that trigger the following actions:
  • Code pushed
  • Pull request created
  • Pull request updated
• Supported actions to take when events occur:
  • Send an HTTP message

For more information, see the Extension example GitHub repo. For a list of all supported events you can use as triggers for your custom consumer extension, see List of event types.

How service hooks work

Service hook publishers define a set of events. Subscriptions listen for the events and define actions that run when an event triggers.

This diagram shows the general service hook flow: publishers emit events, subscriptions match events, and actions run when a match occurs. In this article's example, an extension implements the consumer. When a supported event occurs, the consumer's configured action sends an HTTP message to the endpoint you specify in the extension manifest.

Create the extension

1. See how to create your extension from scratch.

2. Add the specific contribution for custom consumer implementation to your basic manifest file. See the following example of how your manifest should look after you add the contribution.

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

For each contribution in your extension, the manifest defines the following items.

• Type of contribution - consumer service (ms.vss-servicehooks.consumer) in this case.
• Contribution target - consumer services (ms.vss-servicehooks.consumers) in this case.
• Properties that are specific to each type of contribution.

Consumers have the following properties.

Actions for your consumer have the following properties:

3. Deploy your extension to your Azure DevOps organization and test it.

Next steps

Related content

• Service hook consumers
• Available services for service hooks
• Create a service hook subscription programmatically
• Test and debug extensions in the browser
• Extension example GitHub repository
• List of event types