Notifications - Query

Reference

Service:: Service Hooks

API Version:: 7.1-preview.1

Query for notifications. A notification includes details about the event, the request to and the response from the consumer service.

POST https://dev.azure.com/{organization}/_apis/hooks/notificationsquery?api-version=7.1-preview.1

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
api-version	query	True	string	Version of the API to use. This should be set to '7.1-preview.1' to use this version of the api.

Request Body

Name	Type	Description
associatedSubscriptions	Subscription[]	The subscriptions associated with the notifications returned from the query
includeDetails	boolean	If true, we will return all notification history for the query provided; otherwise, the summary is returned.
maxCreatedDate	string	Optional maximum date at which the notification was created
maxResults	integer	Optional maximum number of overall results to include
maxResultsPerSubscription	integer	Optional maximum number of results for each subscription. Only takes effect when a list of subscription ids is supplied in the query.
minCreatedDate	string	Optional minimum date at which the notification was created
publisherId	string	Optional publisher id to restrict the results to
resultType	NotificationResult	Optional notification result type to filter results to
results	Notification[]	Results from the query
status	NotificationStatus	Optional notification status to filter results to
subscriptionIds	string[]	Optional list of subscription ids to restrict the results to
summary	NotificationSummary[]	Summary of notifications - the count of each result type (success, fail, ..).

Responses

Name	Type	Description
200 OK	NotificationsQuery	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.work	Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries, search work items and to receive notifications about work item events via service hooks.
vso.build	Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to receive notifications about build events via service hooks.
vso.code	Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to search code and get notified about version control events via service hooks.

Definitions

Name	Description
Event	Encapsulates the properties of an event.
FormattedEventMessage	Provides different formats of an event message
IdentityRef
Notification	Defines the data contract of the result of processing an event for a subscription.
NotificationDetails	Defines the data contract of notification details.
NotificationResult	Result of the notification
NotificationResultsSummaryDetail	Summary of a particular result and count.
NotificationsQuery	Defines a query for service hook notifications.
NotificationStatus	Status of the notification
NotificationSummary	Summary of the notifications for a subscription.
ReferenceLinks	The class to represent a collection of REST reference links.
ResourceContainer	The base class for all resource containers, i.e. Account, Collection, Project
SessionToken	Represents a session token to be attached in Events for Consumer actions that need it.
Subscription	Encapsulates an event subscription.
SubscriptionStatus

Event

Encapsulates the properties of an event.

Name	Type	Description
createdDate	string	Gets or sets the UTC-based date and time that this event was created.
detailedMessage	FormattedEventMessage	Gets or sets the detailed message associated with this event.
eventType	string	Gets or sets the type of this event.
id	string	Gets or sets the unique identifier of this event.
message	FormattedEventMessage	Gets or sets the (brief) message associated with this event.
publisherId	string	Gets or sets the identifier of the publisher that raised this event.
resource	object	Gets or sets the data associated with this event.
resourceContainers	<string, ResourceContainer>	Gets or sets the resource containers.
resourceVersion	string	Gets or sets the version of the data associated with this event.
sessionToken	SessionToken	Gets or sets the Session Token that can be used in further interactions

FormattedEventMessage

Provides different formats of an event message

Name	Type	Description
html	string	Gets or sets the html format of the message
markdown	string	Gets or sets the markdown format of the message
text	string	Gets or sets the raw text of the message

IdentityRef

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id	string
imageUrl	string	Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary
inactive	boolean	Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary
isAadIdentity	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)
isDeletedInOrigin	boolean
profileUrl	string	Deprecated - not in use in most preexisting implementations of ToIdentityRef
uniqueName	string	Deprecated - use Domain+PrincipalName instead
url	string	This url is the full route to the source resource of this graph subject.

Notification

Defines the data contract of the result of processing an event for a subscription.

Name	Type	Description
createdDate	string	Gets or sets date and time that this result was created.
details	NotificationDetails	Details about this notification (if available)
eventId	string	The event id associated with this notification
id	integer	The notification id
modifiedDate	string	Gets or sets date and time that this result was last modified.
result	NotificationResult	Result of the notification
status	NotificationStatus	Status of the notification
subscriberId	string	The subscriber Id associated with this notification. This is the last identity who touched in the subscription. In case of test notifications it can be the tester if the subscription is not created yet.
subscriptionId	string	The subscription id associated with this notification

NotificationDetails

Defines the data contract of notification details.

Name	Type	Description
completedDate	string	Gets or sets the time that this notification was completed (response received from the consumer)
consumerActionId	string	Gets or sets this notification detail's consumer action identifier.
consumerId	string	Gets or sets this notification detail's consumer identifier.
consumerInputs	object	Gets or sets this notification detail's consumer inputs.
dequeuedDate	string	Gets or sets the time that this notification was dequeued for processing
errorDetail	string	Gets or sets this notification detail's error detail.
errorMessage	string	Gets or sets this notification detail's error message.
event	Event	Gets or sets this notification detail's event content.
eventType	string	Gets or sets this notification detail's event type.
processedDate	string	Gets or sets the time that this notification was finished processing (just before the request is sent to the consumer)
publisherId	string	Gets or sets this notification detail's publisher identifier.
publisherInputs	object	Gets or sets this notification detail's publisher inputs.
queuedDate	string	Gets or sets the time that this notification was queued (created)
request	string	Gets or sets this notification detail's request.
requestAttempts	integer	Number of requests attempted to be sent to the consumer
requestDuration	number	Duration of the request to the consumer in seconds
response	string	Gets or sets this notification detail's response.

NotificationResult

Result of the notification

Name	Type	Description
failed	string	The notification failed to be sent successfully to the consumer
filtered	string	The notification was filtered by the Delivery Job
pending	string	The notification has not yet completed
succeeded	string	The notification was sent successfully

NotificationResultsSummaryDetail

Summary of a particular result and count.

Name	Type	Description
notificationCount	integer	Count of notification sent out with a matching result.
result	NotificationResult	Result of the notification