Edit

Share via

Service hook consumers

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

You can use a service hook to perform an action on a consumer service when an event occurs in an Azure DevOps project. For example, a service hook can notify a consumer when a build fails.

To configure a service hook, you create a subscription that specifies the event, the consumer, and the action. With some consumers, you create a subscription in the consumer service, not in Azure DevOps. This article provides information about the consumer settings you use when you programmatically create a subscription in Azure DevOps.

You can select from the following consumers when you create a subscription in Azure DevOps:

For information about these consumers and others you can integrate with service hooks, see Available services.

Azure Service Bus

Service Bus is a messaging service that facilitates asynchronous communication between applications and services. As a service hook consumer, it provides integration with Service Bus queues and topics and also with Azure Notification Hubs.

Send a message to a notification hub

This action sends a generic, template notification to a specified instance of Notification Hubs.

  • Consumer ID: azureServiceBus

  • Action ID: serviceBusNotificationHubSend

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    connectionString SAS connection string The shared access signature (SAS) connection string to use to connect with Service Bus. This connection string is available in the Azure portal. string Yes
    notificationHubName Notification hub name The name of the notification hub to send the notification to. The name can contain only letters, numbers, periods, hyphens, forward slashes, and underscores. The name must start and end with a letter or number. The hub should already exist. string Yes
    tagsExpression Tags A tag expression that targets a specific set of devices. For more information, see Routing and tag expressions. string No

Send a message to a Service Bus queue

This action sends a JSON string representation of an event to a specified Service Bus queue. For more information, see Service Bus queues, topics, and subscriptions.

  • Consumer ID: azureServiceBus

  • Action ID: serviceBusQueueSend

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    AuthenticationMechanismInputId Authentication mode The authentication mode to use: either a connection string or a service connection. string No
    ServiceConnectionInputId Azure Resource Manager connections The ID of a service connection. string No
    ServiceBusHostNameInputId Service Bus host name The host name in the Azure portal, in the format sb://<Service-Bus-name>.servicebus.windows.net. string No
    connectionString SAS connection string The SAS connection string to use to connect with Service Bus. This connection string is available in the Azure portal. string No
    queueName Queue name The name of the queue to send the message to. The name can contain only letters, numbers, periods, hyphens, forward slashes, and underscores. The name must start and end with a letter or number. If the queue doesn't exist, it's created if the specified connection string has the necessary permissions. string Yes
    bypassSerializer Send as nonserialized string An option for sending messages to Service Bus as nonserialized strings instead of as .NET serialized strings. Select this setting when the receiver isn't a .NET client, for instance, when the client uses Azure Client Library for Node. boolean No
    resourceDetailsToSend Resource details to send The number of resource fields to send to the queue. Possibilities are all fields, a minimum number, and none. string No
    messagesToSend Messages to send The types of messages to send to the queue. string No
    detailedMessagesToSend Detailed messages to send The types of detailed messages to send to the queue. string No

Send a message to a Service Bus topic

This action sends a JSON string representation of an event to a specified Service Bus topic. For more information, see Use the Azure portal to create a Service Bus topic and subscriptions to the topic.

  • Consumer ID: azureServiceBus

  • Action ID: serviceBusTopicSend

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    AuthenticationMechanismInputId Authentication mode The authentication mode to use. string No
    ServiceConnectionInputId Azure Resource Manager connections The ID of a service connection. string No
    ServiceBusHostNameInputId Service Bus host name The host name in the Azure portal, in the format sb://{Service-Bus-name}.servicebus.windows.net. string No
    connectionString SAS connection string The SAS connection string to use to connect with Service Bus. This connection string is available in the Azure portal. string No
    topicName Topic name The name of the topic to send the message to. The name can contain only letters, numbers, periods, hyphens, forward slashes, and underscores. The name must start and end with a letter or number. If the topic doesn't exist, it's created if the specified connection string has the necessary permissions. string Yes
    bypassSerializer Send as nonserialized string An option for sending messages to Service Bus as nonserialized strings instead of as .NET serialized strings. Select this setting when the receiver isn't a .NET client, for instance, when the client uses Azure Client Library for Node. boolean No
    resourceDetailsToSend Resource details to send The number of resource fields to send to the topic. Possibilities are all fields, a minimum number, and none. string No
    messagesToSend Messages to send The types of messages to send to the topic. string No
    detailedMessagesToSend Detailed messages to send The types of detailed messages to send to the topic. string No

Azure Storage

Storage is a cloud storage solution for various types of data. Azure Queue Storage is a part of Storage that provides messaging queues that can act as service hooks consumers.

Insert a message into a Storage queue

This action inserts a JSON string representation of an event into a specified Storage queue. For more information, see What is Azure Queue Storage?.

  • Consumer ID: azureStorageQueue

  • Action ID: enqueue

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    AuthenticationMechanismInputId Authentication mode The authentication mode to use. string No
    ServiceConnectionInputId Azure Resource Manager connections The ID of a service connection. string No
    accountName Storage account name The name associated with your Storage account. This name is available in the Azure portal. string Yes
    accountKey Storage account key The key associated with your Storage account. string No
    queueName Queue name The lowercase-only name of the queue to use within Storage. A queue with this name gets created if it doesn't already exist. string Yes
    visiTimeout Message visibility timeout The visibility timeout value, in seconds, for the enqueued message, relative to the server time. The value must be greater than or equal to 0 and can't be greater than seven days, or 604,800 seconds. The visibility timeout must be set to a value that's less than the message's time-to-live value. number Yes
    ttl Message time-to-live The time-to-live interval for the queue message, in seconds. The maximum value you can use is seven days, or 604,800 seconds. number Yes
    resourceDetailsToSend Resource details to send The number of resource fields to send to the queue. Possibilities are all fields, a minimum number, and none. string No
    messagesToSend Messages to send The types of messages to send to the queue. string No
    detailedMessagesToSend Detailed messages to send The types of detailed messages to send to the queue. string No

Bamboo

Bamboo is a continuous integration server from Atlassian.

Queue a build

This action queues a Bamboo build.

  • Consumer ID: bamboo

  • Action ID: queueBuild

  • Supported events: git.push, build.complete, tfvc.checkin

  • Settings:

    Input ID Name Description Data type Required
    serverBaseUrl Bamboo base URL The URI that contains the hostname of the Bamboo server. uri Yes
    basicAuthCredentials Basic authentication credentials Standard credentials to use to authenticate to the Bamboo server. To avoid sending credentials in plain text, use the HTTPS protocol to encrypt the credentials via Transport Layer Security (TLS). We recommend using service principals and managed identities in Azure DevOps. string Yes
    planName Plan The name of the plan to queue. string Yes

Datadog

Datadog is a monitoring and analytics platform for cloud environments.

Post an event in Datadog

This action creates an event and corresponding metrics in Datadog.

  • Consumer ID: datadog

  • Action ID: postEventInDatadog

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    apiKey Datadog API Key The access key for your Datadog account. You can find your API key in the Datadog portal. Go to your profile, and then select Organization Settings > API Keys. string Yes
    accountType Datadog Account Type The type of your Datadog account. You can determine your account type from the hostname of the URL that your Datadog account uses:
    - app.datadoghq.com: US
    - app.datadoghq.eu: EU
    - us3.datadoghq.com: US3
    - us5.datadoghq.com: US5
    - ap1.datadoghq.com: AP1
    - app.dog-gov.com: GOV    		 string Yes

Grafana

Grafana is an open-source dashboard and graph editor.

Add an annotation to a Grafana database

This action creates an annotation in Grafana.

  • Consumer ID: grafana

  • Action ID: addAnnotation

  • Supported events: ms.vss-release.deployment-completed-event

  • Settings:

    Input ID Name Description Data type Required
    url Grafana URL The URL to use to post an annotation in Grafana​. uri Yes
    apiToken API token The access token for posting annotations to a Grafana database. For information about creating a token, see Create Service Account tokens and dashboards for an organization. string Yes
    tags Tags The comma-separated list of tags to use for adding annotations​. string Yes
    annotationDeploymentDurationWindow Annotate deployment duration window An option for configuring the duration window of an annotation.
    - When selected, the annotation applies to the time between the start and the completion of deployment.
    - When not selected, the annotation applies to the completion of the deployment.    		 boolean No
    text Text A custom description for an annotation. When not specified, this setting describes the release and status​. This setting can include links, such as <a href="https://www.contoso.com" target="_blank">Contoso</a>. string No
    dashboardId Dashboard The ID of the dashboard to add the annotation to. When an ID isn't specified, the annotation is added at the global level​. string No

Jenkins

Jenkins is a continuous integration server that you can use to build and test software projects continuously.

Trigger a Git build

This action uses the Jenkins Git plug-in to trigger a build in a Git repo.

  • Consumer ID: jenkins

  • Action ID: triggerGitBuild

  • Supported events: git.push, git.pullrequest.merged

  • Settings:

    Input ID Name Description Data type Required
    serverBaseUrl Jenkins base URL The URI that contains the hostname of the Jenkins server. uri Yes
    basicAuthCredentials Basic authentication credentials Standard HTTP authentication credentials. To avoid sending credentials in plain text, use the HTTPS protocol to encrypt the credentials via TLS. We recommend using service principals and managed identities in Azure DevOps. string Yes
    useTfsPlugin Integration level The selected integration level, which is one of two values:
    - The built-in Jenkins API
    - The extended integration provided by the Azure DevOps Server plug-in if that plug-in is installed on the Jenkins server    		 string No

Trigger a generic build

This action triggers a generic Jenkins build that invokes the Jenkins build URL.

  • Consumer ID: jenkins

  • Action ID: triggerGenericBuild

  • Supported events: git.push, git.pullrequest.merged, build.complete, tfvc.checkin, ms.vss-release.deployment-completed-event

  • Settings:

    Input ID Name Description Data type Required
    serverBaseUrl Jenkins base URL The URI that contains the hostname of the Jenkins server. uri Yes
    basicAuthCredentials Basic authentication credentials Standard HTTP authentication credentials. To avoid sending credentials in plain text, use the HTTPS protocol to encrypt the credentials via TLS. We recommend using service principals and managed identities in Azure DevOps. string Yes
    buildName Build The name of the build to trigger. string Yes
    useTfsPlugin Integration level The selected integration level, which is one of two values:
    - The built-in Jenkins API
    - The extended integration provided by the Azure DevOps Server plug-in if that plug-in is installed on the Jenkins server    		 string No
    buildAuthToken Build token An authorization token for a build. Only users who know the token can remotely trigger builds. string No
    buildParameterized Accepts parameters An option that specifies whether the build accepts parameters. boolean No
    buildParams Build parameters Build parameters in the form of name-value pairs. In each pair, the name and value are separated by a colon, such as <parameter>:<value>. Each name-value pair appears on its own line. string No

Slack

Slack is a searchable platform for team communication.

Post a message to a channel

This action posts a message about an event to a Slack channel. For more information, see Create a service hook for Azure DevOps with Slack.

  • Consumer ID: slack

  • Action ID: postMessageToChannel

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    url Slack webhook URL The webhook URL provided by Slack to send HTTP POST requests to. uri Yes

Trello

Trello is a project management tool that uses boards, lists, and cards to help teams track workflows.

Create a card

This action creates a card on an existing list in Trello. A card can represent a task, an issue, an event, or other project-related items. For more information, see Create a service hook for Azure DevOps Services and TFS with Trello.

  • Consumer ID: trello

  • Action ID: createCard

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    userToken User token A user token that provides access to Trello resources. To get a token, go to the Trello authorization page. string Yes
    boardId Board The name of the board on which the Trello card gets created. string Yes
    listId List The name of the list on which the Trello card gets created. string Yes
    labels Labels A comma-separated list of label colors to apply to the created card. Valid label color names are red, orange, yellow, green, blue, and purple. string No
    addToTop Create at beginning of list An option that indicates whether to create the card at the beginning or end of the Trello list. When this field is true, the card is created at the beginning. boolean No
    cardName Card name The name for the new card. By default, the text description of the event is used as the name. You can use placeholders to insert content from the event into the name. For more information, see Create a service hook for Azure DevOps Services and TFS with Trello. string No
    cardDescription Card description The description for the new card. By default, the detailed Markdown description of the event is used as the description. You can use placeholders to insert content from the event into the description. For more information, see Create a service hook for Azure DevOps Services and TFS with Trello. string No

Create a list

This action creates a list on an existing board in Trello. A list is used to organize cards on a board and typically represents a state. For more information, see Create a service hook for Azure DevOps Services and TFS with Trello.

  • Consumer ID: trello

  • Action ID: createList

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    userToken User token A user token that provides access to Trello resources. To get a token, go to the Trello authorization page. string Yes
    boardId Board The name of the board on which the Trello list gets created. string Yes
    addToBottom Create at bottom of board An option that indicates whether to create the card at the beginning or end of the board. When this field is true, the card is created at the end. boolean No
    listName List name The name for the new list. By default, the text description of the event is used as the name. You can use placeholders to insert content from the event into the name. For more information, see Create a service hook for Azure DevOps Services and TFS with Trello. string No

Webhooks

Webhooks provide a way to send a JSON representation of an Azure DevOps event to any service that has a public endpoint.

Post via HTTP

This action posts a JSON object representation of an event to a specified URL. HTTPS endpoints are recommended due to the potential for private data in the event payload. For more information, see Webhooks.

  • Consumer ID: webHooks

  • Action ID: httpRequest

  • Supported events: All events

  • Settings:

    Input ID Name Description Data type Required
    url URL The URL to send an HTTP POST to. uri Yes
    acceptUntrustedCerts Accept untrusted SSL certificates An option for not requiring a trusted Secure Sockets Layer (SSL) certificate for an endpoint. Use this option only during development and testing. boolean No
    basicAuthCredentials Basic authentication credentials Standard HTTP authentication credentials. To avoid sending credentials in plain text, use the HTTPS protocol to encrypt the credentials via TLS. We recommend using service principals and managed identities in Azure DevOps. string Yes
    httpHeaders HTTP headers HTTP header keys and values in the form of key-value pairs. In each pair, the key and value are separated by a colon, such as <key>:<value>. Each key-value pair appears on its own line. These values are viewable by anyone who has access to the service hook subscription. string No
    resourceDetailsToSend Resource details to send The number of resource fields to send to the queue. Possibilities are all fields, a minimum number, and none. string No
    messagesToSend Messages to send The types of messages to send to the queue. string No
    detailedMessagesToSend Detailed messages to send The types of detailed messages to send to the queue. string No

Zendesk

Zendesk is a software as a service (SaaS) suite that offers help-desk ticketing, issue tracking, and customer-service support.

Create a private comment in a ticket

This action creates a private comment in a Zendesk ticket.

  • Consumer ID: zendesk

  • Action ID: createPrivateComment

  • Supported events: workitem.commented

  • Settings:

    Input ID Name Description Data type Required
    accountName Account name The Zendesk account name. You can find the account name in the URL of your Zendesk account, which has the format https://<account-name>.zendesk.com. string Yes
    username User name The user name of the Zendesk user who updates tickets. string Yes
    apiToken API token The Zendesk API token. To find the token, go to the Zendesk app, and then select Admin > Channels > API. string Yes

Related content