openapi: 3.0.4 info: title: ChangeNotifications version: v1.0 servers: - url: https://graph.microsoft.com/v1.0/ description: Core paths: /subscriptions: get: tags: - subscriptions.subscription summary: List subscriptions description: 'Retrieve the properties and relationships of webhook subscriptions, based on the app ID, the user, and the user''s role with a tenant. The content of the response depends on the context in which the app is calling; for details, see the scenarios in the Permissions section.' externalDocs: description: Find more info here url: https://learn.microsoft.com/graph/api/subscription-list?view=graph-rest-1.0 operationId: subscription_ListSubscription parameters: - $ref: '#/components/parameters/top' - $ref: '#/components/parameters/skip' - $ref: '#/components/parameters/search' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/count' - name: $orderby in: query description: Order items by property values style: form explode: false schema: uniqueItems: true type: array items: type: string - name: $select in: query description: Select properties to be returned style: form explode: false schema: uniqueItems: true type: array items: type: string - name: $expand in: query description: Expand related entities style: form explode: false schema: uniqueItems: true type: array items: type: string responses: 2XX: $ref: '#/components/responses/microsoft.graph.subscriptionCollectionResponse' default: $ref: '#/components/responses/error' x-ms-pageable: nextLinkName: '@odata.nextLink' operationName: listMore x-ms-docs-operation-type: operation post: tags: - subscriptions.subscription summary: Create subscription description: 'Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph. To identify the resources for which you can create subscriptions and the limitations on subscriptions, see Set up notifications for changes in resource data: Supported resources. Some resources support rich notifications, that is, notifications that include resource data. For more information about these resources, see Set up change notifications that include resource data: Supported resources.' externalDocs: description: Find more info here url: https://learn.microsoft.com/graph/api/subscription-post-subscriptions?view=graph-rest-1.0 operationId: subscription_CreateSubscription requestBody: description: New entity content: application/json: schema: $ref: '#/components/schemas/microsoft.graph.subscription' required: true responses: 2XX: description: Created entity content: application/json: schema: $ref: '#/components/schemas/microsoft.graph.subscription' default: $ref: '#/components/responses/error' x-ms-docs-operation-type: operation '/subscriptions/{subscription-id}': get: tags: - subscriptions.subscription summary: Get subscription description: Retrieve the properties and relationships of a subscription. See the table in the Permissions section for the list of resources that support subscribing to change notifications. externalDocs: description: Find more info here url: https://learn.microsoft.com/graph/api/subscription-get?view=graph-rest-1.0 operationId: subscription_GetSubscription parameters: - name: subscription-id in: path description: The unique identifier of subscription required: true style: simple schema: type: string x-ms-docs-key-type: subscription - name: $select in: query description: Select properties to be returned style: form explode: false schema: uniqueItems: true type: array items: type: string responses: 2XX: description: Retrieved entity content: application/json: schema: $ref: '#/components/schemas/microsoft.graph.subscription' default: $ref: '#/components/responses/error' x-ms-docs-operation-type: operation patch: tags: - subscriptions.subscription summary: Update subscription description: 'Renew a subscription by extending its expiry time. The table in the Permissions section lists the resources that support subscribing to change notifications. Subscriptions expire after a length of time that varies by resource type. In order to avoid missing change notifications, an app should renew its subscriptions well in advance of their expiry date. See subscription for maximum length of a subscription for each resource type.' externalDocs: description: Find more info here url: https://learn.microsoft.com/graph/api/subscription-update?view=graph-rest-1.0 operationId: subscription_UpdateSubscription parameters: - name: subscription-id in: path description: The unique identifier of subscription required: true style: simple schema: type: string x-ms-docs-key-type: subscription requestBody: description: New property values content: application/json: schema: $ref: '#/components/schemas/microsoft.graph.subscription' required: true responses: 2XX: description: Success content: application/json: schema: $ref: '#/components/schemas/microsoft.graph.subscription' default: $ref: '#/components/responses/error' x-ms-docs-operation-type: operation delete: tags: - subscriptions.subscription summary: Delete subscription description: 'Delete a subscription. For the list of resources that support subscribing to change notifications, see the table in the Permissions section.' externalDocs: description: Find more info here url: https://learn.microsoft.com/graph/api/subscription-delete?view=graph-rest-1.0 operationId: subscription_DeleteSubscription parameters: - name: subscription-id in: path description: The unique identifier of subscription required: true style: simple schema: type: string x-ms-docs-key-type: subscription - name: If-Match in: header description: ETag style: simple schema: type: string responses: 2XX: description: Success default: $ref: '#/components/responses/error' x-ms-docs-operation-type: operation '/subscriptions/{subscription-id}/microsoft.graph.reauthorize': post: tags: - subscriptions.subscription.Actions summary: Invoke action reauthorize description: Reauthorize a subscription when you receive a reauthorizationRequired challenge. externalDocs: description: Find more info here url: https://learn.microsoft.com/graph/api/subscription-reauthorize?view=graph-rest-1.0 operationId: subscription_reauthorize parameters: - name: subscription-id in: path description: The unique identifier of subscription required: true style: simple schema: type: string x-ms-docs-key-type: subscription responses: 2XX: description: Success default: $ref: '#/components/responses/error' x-ms-docs-operation-type: action components: schemas: microsoft.graph.subscription: allOf: - $ref: '#/components/schemas/microsoft.graph.entity' - title: subscription type: object properties: applicationId: type: string description: Optional. Identifier of the application used to create the subscription. Read-only. nullable: true changeType: type: string description: 'Required. Indicates the type of change in the subscribed resource that raises a change notification. The supported values are: created, updated, deleted. Multiple values can be combined using a comma-separated list. Note: Drive root item and list change notifications support only the updated changeType. User and group change notifications support updated and deleted changeType. Use updated to receive notifications when user or group is created, updated, or soft deleted. Use deleted to receive notifications when user or group is permanently deleted.' clientState: type: string description: Optional. Specifies the value of the clientState property sent by the service in each change notification. The maximum length is 128 characters. The client can check that the change notification came from the service by comparing the value of the clientState property sent with the subscription with the value of the clientState property received with each change notification. nullable: true creatorId: type: string description: 'Optional. Identifier of the user or service principal that created the subscription. If the app used delegated permissions to create the subscription, this field contains the ID of the signed-in user the app called on behalf of. If the app used application permissions, this field contains the ID of the service principal corresponding to the app. Read-only.' nullable: true encryptionCertificate: type: string description: Optional. A base64-encoded representation of a certificate with a public key used to encrypt resource data in change notifications. Optional but required when includeResourceData is true. nullable: true encryptionCertificateId: type: string description: Optional. A custom app-provided identifier to help identify the certificate needed to decrypt resource data. nullable: true expirationDateTime: pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$' type: string description: 'Required. Specifies the date and time when the webhook subscription expires. The time is in UTC, and can be an amount of time from subscription creation that varies for the resource subscribed to. Any value under 45 minutes after the time of the request is automatically set to 45 minutes after the request time. For the maximum supported subscription length of time, see Subscription lifetime.' format: date-time includeResourceData: type: boolean description: 'Optional. When set to true, change notifications include resource data (such as content of a chat message).' nullable: true latestSupportedTlsVersion: type: string description: 'Optional. Specifies the latest version of Transport Layer Security (TLS) that the notification endpoint, specified by notificationUrl, supports. The possible values are: v10, v11, v12, v13. For subscribers whose notification endpoint supports a version lower than the currently recommended version (TLS 1.2), specifying this property by a set timeline allows them to temporarily use their deprecated version of TLS before completing their upgrade to TLS 1.2. For these subscribers, not setting this property per the timeline would result in subscription operations failing. For subscribers whose notification endpoint already supports TLS 1.2, setting this property is optional. In such cases, Microsoft Graph defaults the property to v1_2.' nullable: true lifecycleNotificationUrl: type: string description: 'Required for Teams resources if the expirationDateTime value is more than 1 hour from now; optional otherwise. The URL of the endpoint that receives lifecycle notifications, including subscriptionRemoved, reauthorizationRequired, and missed notifications. This URL must make use of the HTTPS protocol. For more information, see Reduce missing subscriptions and change notifications.' nullable: true notificationQueryOptions: type: string description: 'Optional. OData query options for specifying value for the targeting resource. Clients receive notifications when resource reaches the state matching the query options provided here. With this new property in the subscription creation payload along with all existing properties, Webhooks deliver notifications whenever a resource reaches the desired state mentioned in the notificationQueryOptions property. For example, when the print job is completed or when a print job resource isFetchable property value becomes true etc. Supported only for Universal Print Service. For more information, see Subscribe to change notifications from cloud printing APIs using Microsoft Graph.' nullable: true notificationUrl: type: string description: Required. The URL of the endpoint that receives the change notifications. This URL must make use of the HTTPS protocol. Any query string parameter included in the notificationUrl property is included in the HTTP POST request when Microsoft Graph sends the change notifications. notificationUrlAppId: type: string description: Optional. The app ID that the subscription service can use to generate the validation token. The value allows the client to validate the authenticity of the notification received. nullable: true resource: type: string description: Required. Specifies the resource that is monitored for changes. Don't include the base URL (https://graph.microsoft.com/v1.0/). See the possible resource path values for each supported resource. additionalProperties: type: object microsoft.graph.entity: title: entity type: object properties: id: type: string description: The unique identifier for an entity. Read-only. additionalProperties: type: object microsoft.graph.subscriptionCollectionResponse: title: Collection of subscription type: object properties: value: type: array items: $ref: '#/components/schemas/microsoft.graph.subscription' '@odata.nextLink': type: string nullable: true additionalProperties: type: object microsoft.graph.ODataErrors.ODataError: required: - error type: object properties: error: $ref: '#/components/schemas/microsoft.graph.ODataErrors.MainError' additionalProperties: type: object microsoft.graph.ODataErrors.MainError: required: - code - message type: object properties: code: type: string message: type: string x-ms-primary-error-message: true target: type: string nullable: true details: type: array items: $ref: '#/components/schemas/microsoft.graph.ODataErrors.ErrorDetails' innerError: $ref: '#/components/schemas/microsoft.graph.ODataErrors.InnerError' additionalProperties: type: object microsoft.graph.ODataErrors.ErrorDetails: required: - code - message type: object properties: code: type: string message: type: string target: type: string nullable: true additionalProperties: type: object microsoft.graph.ODataErrors.InnerError: type: object additionalProperties: type: object description: The structure of this object is service-specific responses: microsoft.graph.subscriptionCollectionResponse: description: Retrieved collection content: application/json: schema: $ref: '#/components/schemas/microsoft.graph.subscriptionCollectionResponse' error: description: error content: application/json: schema: $ref: '#/components/schemas/microsoft.graph.ODataErrors.ODataError' parameters: top: name: $top in: query description: Show only the first n items style: form explode: false schema: minimum: 0 type: integer example: 50 skip: name: $skip in: query description: Skip the first n items style: form explode: false schema: minimum: 0 type: integer search: name: $search in: query description: Search items by search phrases style: form explode: false schema: type: string filter: name: $filter in: query description: Filter items by property values style: form explode: false schema: type: string count: name: $count in: query description: Include count of items style: form explode: false schema: type: boolean securitySchemes: azureaadv2: type: oauth2 flows: authorizationCode: authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token scopes: { } security: - azureaadv2: [ ]