openapi: 3.1.0
info:
title: Azure DevOps Service Hooks API
description: >
REST API for managing service hook subscriptions, publishers, and consumers
in Azure DevOps. Service hooks enable event-driven integrations by delivering
notifications to external services (webhooks, Azure Service Bus, Teams, Slack,
etc.) when Azure DevOps events occur such as work item changes, build completions,
and pull request updates.
version: '7.1'
contact:
name: Microsoft Azure DevOps
url: https://learn.microsoft.com/en-us/rest/api/azure/devops/hooks/
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://dev.azure.com/{organization}/_apis
description: Azure DevOps Service Hooks API (organization-level, no project scope)
variables:
organization:
description: Azure DevOps organization name or ID
default: myorganization
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Consumers
description: Operations for listing consumers (webhook, service bus, etc.)
- name: Notifications
description: Operations for sending test notifications
- name: Publishers
description: Operations for listing event publishers and their event types
- name: Subscriptions
description: Operations for managing service hook subscriptions
paths:
/hooks/subscriptions:
get:
operationId: subscriptions_list
summary: Azure DevOps List subscriptions
description: >
Returns a list of all service hook subscriptions in the organization.
Each subscription specifies an event type, publisher, consumer (webhook endpoint),
and filter conditions. Supports optional filtering by publisher and consumer.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: publisherId
in: query
required: false
description: Filter subscriptions by publisher ID (e.g., 'tfs')
schema:
type: string
- name: eventType
in: query
required: false
description: Filter subscriptions by event type (e.g., 'workitem.created')
schema:
type: string
- name: consumerId
in: query
required: false
description: Filter subscriptions by consumer ID (e.g., 'webHooks')
schema:
type: string
- name: consumerActionId
in: query
required: false
description: Filter subscriptions by consumer action ID
schema:
type: string
responses:
'200':
description: List of subscriptions returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: Number of subscriptions returned
value:
type: array
items:
$ref: '#/components/schemas/Subscription'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
post:
operationId: subscriptions_create
summary: Azure DevOps Create a subscription
description: >
Creates a new service hook subscription. The subscription defines which
event to listen for (publisher + eventType), filter conditions to narrow
the event scope (e.g., a specific project or branch), and the consumer
endpoint to deliver the notification to.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/ApiVersion'
requestBody:
required: true
description: Subscription configuration
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreateRequest'
example:
publisherId: 'tfs'
eventType: 'workitem.created'
resourceVersion: '1.0'
consumerId: 'webHooks'
consumerActionId: 'httpRequest'
publisherInputs:
projectId: 'a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4'
workItemType: 'Bug'
areaPath: 'MyProject'
consumerInputs:
url: 'https://myserver.example.com/webhook'
httpHeaders: 'X-Custom-Header: my-value'
messagesToSend: 'none'
detailedMessagesToSend: 'all'
resourceDetailsToSend: 'all'
responses:
'200':
description: Subscription created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/hooks/subscriptions/{subscriptionId}:
get:
operationId: subscriptions_get
summary: Azure DevOps Get a subscription
description: >
Returns detailed information about a specific service hook subscription,
including its publisher, event type, consumer configuration, filter inputs,
and current status.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: subscriptionId
in: path
required: true
description: GUID of the subscription
schema:
type: string
format: uuid
responses:
'200':
description: Subscription returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: subscriptions_update
summary: Azure DevOps Update a subscription
description: >
Updates properties of an existing service hook subscription such as
the consumer endpoint URL, filter conditions, or resource detail settings.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: subscriptionId
in: path
required: true
description: GUID of the subscription to update
schema:
type: string
format: uuid
requestBody:
required: true
description: Updated subscription properties
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreateRequest'
responses:
'200':
description: Subscription updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: subscriptions_delete
summary: Azure DevOps Delete a subscription
description: >
Permanently deletes a service hook subscription. After deletion, the
consumer endpoint will no longer receive notifications for the configured
event type.
tags:
- Subscriptions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: subscriptionId
in: path
required: true
description: GUID of the subscription to delete
schema:
type: string
format: uuid
responses:
'204':
description: Subscription deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/hooks/publishers:
get:
operationId: publishers_list
summary: Azure DevOps List publishers
description: >
Returns a list of all available publishers (event sources) that can be
subscribed to. The primary publisher for Azure DevOps events is 'tfs'.
Each publisher defines what event types it can produce.
tags:
- Publishers
parameters:
- $ref: '#/components/parameters/ApiVersion'
responses:
'200':
description: List of publishers returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/Publisher'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/hooks/publishers/{publisherId}/eventTypes:
get:
operationId: publishers_listEventTypes
summary: Azure DevOps List event types for a publisher
description: >
Returns all event types defined by a specific publisher. Each event type
includes its ID, name, description, and the input parameters that can be
used to filter notifications.
tags:
- Publishers
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: publisherId
in: path
required: true
description: Publisher identifier (e.g., 'tfs')
schema:
type: string
example: 'tfs'
responses:
'200':
description: List of event types returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/EventType'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/hooks/consumers:
get:
operationId: consumers_list
summary: Azure DevOps List consumers
description: >
Returns a list of all available consumers that can receive service hook
notifications. Consumers include webhooks (httpRequest), Azure Service Bus,
Azure Storage, Microsoft Teams, and other integration targets.
tags:
- Consumers
parameters:
- $ref: '#/components/parameters/ApiVersion'
responses:
'200':
description: List of consumers returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/Consumer'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/hooks/testnotifications:
post:
operationId: notifications_sendTest
summary: Azure DevOps Send a test notification
description: >
Sends a test notification to verify that a service hook subscription is
correctly configured and the consumer endpoint is reachable. Returns the
result of the delivery attempt including HTTP status code and response body.
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: useRealData
in: query
required: false
description: Whether to use real event data or synthetic test data
schema:
type: boolean
requestBody:
required: true
description: Subscription configuration to test
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreateRequest'
example:
publisherId: 'tfs'
eventType: 'workitem.created'
resourceVersion: '1.0'
consumerId: 'webHooks'
consumerActionId: 'httpRequest'
publisherInputs:
projectId: 'a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4'
consumerInputs:
url: 'https://myserver.example.com/webhook'
responses:
'200':
description: Test notification sent, result returned
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Azure AD OAuth 2.0 bearer token
basicAuth:
type: http
scheme: basic
description: Basic authentication using a Personal Access Token (PAT). Use any string as the username and the PAT as the password, then base64-encode the result.
parameters:
ApiVersion:
name: api-version
in: query
required: true
description: Azure DevOps REST API version. Use 7.1 for the latest stable version.
schema:
type: string
default: '7.1'
enum: ['7.1', '7.0', '6.0']
responses:
BadRequest:
description: Bad request - invalid parameters or request body
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Unauthorized:
description: Unauthorized - missing or invalid authentication credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Forbidden:
description: Forbidden - insufficient permissions to perform this operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
NotFound:
description: Not found - the requested resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
schemas:
Subscription:
type: object
description: A service hook subscription that delivers event notifications to a consumer
properties:
id:
type: string
format: uuid
description: Unique GUID identifier of the subscription
status:
type: string
description: Current health status of the subscription
enum: [enabled, onProbation, disabledByUser, disabledBySystem, disabledByInactiveIdentity]
publisherId:
type: string
description: Identifier of the publisher (event source)
example: 'tfs'
eventType:
type: string
description: Type of event this subscription listens for
example: 'workitem.created'
resourceVersion:
type: string
description: Version of the event resource schema
example: '1.0'
consumerId:
type: string
description: Identifier of the consumer (notification target)
example: 'webHooks'
consumerActionId:
type: string
description: Identifier of the specific consumer action
example: 'httpRequest'
publisherInputs:
type: object
description: Filter inputs for the event publisher (project ID, event conditions)
additionalProperties:
type: string
example:
projectId: 'a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4'
workItemType: 'Bug'
areaPath: 'MyProject'
consumerInputs:
type: object
description: Configuration inputs for the consumer (URL, headers, auth)
additionalProperties:
type: string
example:
url: 'https://myserver.example.com/webhook'
resourceDetailsToSend: 'all'
modifiedBy:
$ref: '#/components/schemas/IdentityRef'
modifiedDate:
type: string
format: date-time
description: Date and time the subscription was last modified
createdBy:
$ref: '#/components/schemas/IdentityRef'
createdDate:
type: string
format: date-time
description: Date and time the subscription was created
url:
type: string
format: uri
description: URL to access this subscription via the REST API
_links:
type: object
additionalProperties:
type: object
properties:
href:
type: string
format: uri
SubscriptionCreateRequest:
type: object
description: Request body for creating or updating a service hook subscription
required:
- publisherId
- eventType
- consumerId
- consumerActionId
- publisherInputs
- consumerInputs
properties:
publisherId:
type: string
description: Publisher ID for the event source
example: 'tfs'
eventType:
type: string
description: Event type to subscribe to
example: 'workitem.created'
resourceVersion:
type: string
description: Version of the event resource schema to use
example: '1.0'
default: '1.0'
consumerId:
type: string
description: Consumer ID for the notification target
example: 'webHooks'
consumerActionId:
type: string
description: Action ID within the consumer
example: 'httpRequest'
publisherInputs:
type: object
description: Filter inputs controlling which events trigger a notification
additionalProperties:
type: string
consumerInputs:
type: object
description: Configuration for the consumer endpoint
additionalProperties:
type: string
Publisher:
type: object
description: An event publisher (source) that can produce service hook events
properties:
id:
type: string
description: Unique identifier of the publisher
example: 'tfs'
name:
type: string
description: Display name of the publisher
example: 'Azure DevOps'
description:
type: string
description: Description of the publisher and the events it produces
supportedEvents:
type: array
description: List of event types this publisher supports
items:
$ref: '#/components/schemas/EventTypeReference'
inputs:
type: array
description: Input parameters for filtering publisher events
items:
$ref: '#/components/schemas/InputDescriptor'
url:
type: string
format: uri
EventType:
type: object
description: An event type that a publisher can produce
properties:
id:
type: string
description: Unique identifier of the event type
example: 'workitem.created'
name:
type: string
description: Display name of the event type
example: 'Work item created'
description:
type: string
description: Detailed description of when this event fires
publisherId:
type: string
description: ID of the publisher that produces this event
supportedResourceVersions:
type: array
description: Supported versions of the event resource schema
items:
type: string
fields:
type: object
description: Fields available in the event payload
additionalProperties:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
fieldType:
type: string
isFilterable:
type: boolean
isQueryable:
type: boolean
EventTypeReference:
type: object
description: Minimal reference to an event type
properties:
id:
type: string
description: Event type identifier
name:
type: string
description: Event type display name
Consumer:
type: object
description: A consumer that can receive service hook notifications
properties:
id:
type: string
description: Unique identifier of the consumer
example: 'webHooks'
name:
type: string
description: Display name of the consumer
example: 'Web Hooks'
description:
type: string
description: Description of this consumer type
imageUrl:
type: string
format: uri
description: URL to the consumer's icon
informationUrl:
type: string
format: uri
description: Documentation URL for this consumer
actions:
type: array
description: Available actions for this consumer
items:
$ref: '#/components/schemas/ConsumerAction'
inputs:
type: array
description: Configuration inputs for this consumer
items:
$ref: '#/components/schemas/InputDescriptor'
url:
type: string
format: uri
ConsumerAction:
type: object
description: An action available in a consumer
properties:
id:
type: string
description: Action identifier
example: 'httpRequest'
name:
type: string
description: Action display name
example: 'Send a generic HTTP request with a JSON payload'
description:
type: string
description: Description of what this action does
consumerId:
type: string
description: Parent consumer ID
inputs:
type: array
description: Input parameters required for this action
items:
$ref: '#/components/schemas/InputDescriptor'
url:
type: string
format: uri
InputDescriptor:
type: object
description: Descriptor for a configurable input parameter
properties:
id:
type: string
description: Input identifier
name:
type: string
description: Display name
description:
type: string
description: Help text
inputMode:
type: string
description: How the input is presented in UI
enum: [none, textBox, passwordBox, combo, radioButtons, checkBox, textArea]
isConfidential:
type: boolean
description: Whether the value is treated as a secret
isRequired:
type: boolean
description: Whether this input is required
values:
type: object
description: Allowed values for combo/radio inputs
properties:
defaultValue:
type: string
possibleValues:
type: array
items:
type: object
properties:
value:
type: string
displayValue:
type: string
validation:
type: object
description: Validation rules for this input
properties:
dataType:
type: string
enum: [none, string, number, boolean, guid, uri]
isRequired:
type: boolean
pattern:
type: string
description: Regex pattern for validation
patternMismatchErrorMessage:
type: string
minLength:
type: integer
maxLength:
type: integer
NotificationResult:
type: object
description: Result of a test notification delivery attempt
properties:
id:
type: integer
description: Notification ID
subscriptionId:
type: string
format: uuid
description: ID of the subscription used for the test
result:
type: string
description: Delivery result status
enum: [pending, processing, requestInProgress, delivered, dequeued, abandoned, error, filteredBySubscriber]
status:
type: string
description: HTTP status description from the consumer
createdDate:
type: string
format: date-time
modifiedDate:
type: string
format: date-time
details:
type: object
description: Detailed delivery attempt information
properties:
errorMessage:
type: string
errorDetail:
type: string
deliveryAttempts:
type: array
items:
type: object
properties:
result:
type: string
status:
type: string
requestData:
type: object
properties:
headers:
type: object
additionalProperties:
type: string
body:
type: string
responseData:
type: object
properties:
statusCode:
type: integer
headers:
type: object
additionalProperties:
type: string
body:
type: string
startTime:
type: string
format: date-time
endTime:
type: string
format: date-time
IdentityRef:
type: object
description: Reference to an Azure DevOps user identity
properties:
id:
type: string
format: uuid
displayName:
type: string
example: 'John Doe'
uniqueName:
type: string
example: '[email protected]'
url:
type: string
format: uri
imageUrl:
type: string
format: uri
descriptor:
type: string
ApiError:
type: object
description: Error response from the Azure DevOps API
properties:
id:
type: string
format: uuid
message:
type: string
typeName:
type: string
typeKey:
type: string
errorCode:
type: integer
eventId:
type: integer