Microsoft Entra ID Change Notifications API

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: [ ]