Skip to content

add-service-hook.md

Latest commit

 

History

History
175 lines (146 loc) · 8.37 KB

add-service-hook.md

File metadata and controls

175 lines (146 loc) · 8.37 KB
ms.subservice azure-devops-ecosystem
title Create a custom consumer for service hooks
description Learn how to create a custom consumer for service hooks in Azure DevOps.
ms.assetid 294ae93b-7522-40ef-95ab-d5002f8c3ca8
ms.custom engagement-fy23
ms.topic how-to
monikerRange <= azure-devops
ms.author chcomley
author chcomley
ms.date 10/03/2025

Create a custom consumer for service hooks

[!INCLUDE version-lt-eq-azure-devops]

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.

[!INCLUDE extension-samples-tip]

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

Note

This article refers to the home directory for your project as home.

:::image type="content" source="media/consumer-service.png" alt-text="Diagram that shows a sample consumer service sending HTTP messages for code push and pull request events.":::

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.

[!INCLUDE extension-docs-new-sdk]

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.

:::image type="content" source="media/service-hooks.png" alt-text="Diagram that shows the service hook flow: publishers emit events, subscriptions match events, and actions run when an event matches a subscription.":::

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

Note

Remember to update the publisher property.

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.

Property Description
id Unique ID for your consumer service.
name Name of the custom consumer, which is visible during service hook subscription creation.
description Describes your consumer service.
informationUrl Find more info 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 those actions.

Actions for your consumer have the following properties:

Property Description
id ID for your action service.
name Name of the action.
description Detailed description of the action.
supportedEventTypes Array of trigger types for which this action can be used. For more information, see List of event types.
publishEvent.url The endpoint URL that receives the HTTP message. You can template this value with tokens from the inputDescriptors; users provide the actual values when they create the subscription.
  1. Deploy your extension to your Azure DevOps organization and test it.

Next steps

[!div class="nextstepaction"] Package, publish, and install extensions

Related content