Microsoft Graph Change Notifications

asyncapi: 2.6.0
info:
  title: Microsoft Graph Change Notifications
  description: Microsoft Graph change notifications enable applications to receive real-time notifications when data changes occur in Microsoft Graph resources. Applications create subscriptions specifying
    which resources to monitor and a webhook endpoint to receive notifications. When a change occurs (create, update, or delete), Microsoft Graph sends a POST request to the specified notification URL containing
    one or more changeNotification objects wrapped in a changeNotificationCollection. Supported resources include Outlook messages, events, and contacts; Teams chats, channels, and messages; OneDrive and
    SharePoint items; directory objects such as users and groups; security alerts; and presence information. Notifications can optionally include encrypted resource data for rich notification scenarios.
    Lifecycle notifications inform apps about subscription expiration, removal, and reauthorization requirements.
  version: '1.0'
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
servers:
  production:
    url: https://graph.microsoft.com/v1.0
    protocol: https
    description: Microsoft Graph v1.0 production endpoint. Applications create subscriptions via the REST API, and Microsoft Graph delivers change notifications to the application's webhook endpoint.
    security:
    - oauth2: []
channels:
  /webhook:
    description: The webhook endpoint hosted by the subscribing application. Microsoft Graph sends HTTP POST requests to this URL when changes occur in subscribed resources. The endpoint must support HTTPS,
      respond to validation requests during subscription creation, and return HTTP 202 Accepted for notification deliveries.
    publish:
      operationId: receiveChangeNotifications
      summary: Receive change notifications from Microsoft Graph
      description: Microsoft Graph delivers change notification payloads to the subscriber's webhook endpoint as HTTP POST requests. Each payload is a changeNotificationCollection containing one or more
        changeNotification objects. The subscriber must respond with HTTP 202 Accepted within 3 seconds to acknowledge receipt. Notifications may include basic resource references or encrypted resource
        data depending on the subscription configuration.
      message:
        oneOf:
        - $ref: '#/components/messages/ChangeNotificationCollection'
        - $ref: '#/components/messages/ValidationRequest'
  /lifecycleNotifications:
    description: The lifecycle notification endpoint hosted by the subscribing application, specified via the lifecycleNotificationUrl property when creating a subscription. Microsoft Graph sends lifecycle
      events to inform the application about subscription state changes including missed notifications, subscription removal, and reauthorization requirements.
    publish:
      operationId: receiveLifecycleNotifications
      summary: Receive lifecycle notifications for subscription management
      description: Microsoft Graph sends lifecycle notifications when a subscription encounters issues that require the application's attention. These include missed notifications (when delivery failed),
        subscription removal (when the subscription was removed by the service), and reauthorization required (when the app's access token needs renewal). Applications must handle these events to maintain
        reliable notification delivery.
      message:
        $ref: '#/components/messages/LifecycleNotification'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization using Microsoft identity platform. Applications must register in Microsoft Entra ID and obtain tokens with appropriate permissions to create subscriptions and
        receive change notifications.
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://graph.microsoft.com/.default: Access Microsoft Graph resources
  messages:
    ChangeNotificationCollection:
      name: changeNotificationCollection
      title: Change Notification Collection
      summary: A collection of one or more change notifications delivered to the subscriber's webhook endpoint when subscribed resources change.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ChangeNotificationCollection'
    ValidationRequest:
      name: validationRequest
      title: Webhook Validation Request
      summary: A validation request sent by Microsoft Graph when a subscription is created or renewed. The endpoint must respond with the validationToken value in the response body as plain text within
        10 seconds.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ValidationRequest'
    LifecycleNotification:
      name: lifecycleNotification
      title: Lifecycle Notification
      summary: A lifecycle notification informing the application about subscription state changes that require attention, such as missed notifications, subscription removal, or the need for reauthorization.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/LifecycleNotificationPayload'
  schemas:
    ChangeNotificationCollection:
      type: object
      description: A collection of change notifications sent as a single POST request to the subscriber's webhook endpoint. May contain notifications from multiple subscriptions.
      properties:
        value:
          type: array
          description: The set of change notifications being delivered in this payload.
          items:
            $ref: '#/components/schemas/ChangeNotification'
      required:
      - value
    ChangeNotification:
      type: object
      description: Represents a single change notification for a subscribed resource. Contains information about what changed, which subscription triggered the notification, and optionally the changed resource
        data.
      properties:
        id:
          type: string
          description: Unique identifier for this notification.
        subscriptionId:
          type: string
          format: uuid
          description: The unique identifier of the subscription that generated this notification.
        subscriptionExpirationDateTime:
          type: string
          format: date-time
          description: The expiration date and time of the subscription that generated this notification.
        clientState:
          type: string
          maxLength: 255
          description: The value of the clientState property sent in the subscription request, used to verify the authenticity of the notification.
        changeType:
          type: string
          description: The type of change that triggered the notification.
          enum:
          - created
          - updated
          - deleted
        resource:
          type: string
          description: The URI of the resource that changed, relative to https://graph.microsoft.com.
        resourceData:
          $ref: '#/components/schemas/ResourceData'
        encryptedContent:
          $ref: '#/components/schemas/ChangeNotificationEncryptedContent'
        tenantId:
          type: string
          format: uuid
          description: The unique identifier of the Microsoft Entra tenant from which the change notification originated.
      required:
      - subscriptionId
      - subscriptionExpirationDateTime
      - changeType
      - resource
      - tenantId
    ResourceData:
      type: object
      description: Basic information about the resource that triggered the change notification, including the resource type and identifier.
      properties:
        '@odata.type':
          type: string
          description: 'The OData entity type of the resource, such as #microsoft.graph.message or #microsoft.graph.chatMessage.'
        '@odata.id':
          type: string
          description: The OData identifier for the resource instance.
        '@odata.etag':
          type: string
          description: The HTTP entity tag that represents the version of the resource.
        id:
          type: string
          description: The identifier of the resource that triggered the notification.
    ChangeNotificationEncryptedContent:
      type: object
      description: Encrypted resource data attached to a change notification when the subscription was configured with includeResourceData set to true and an encryption certificate. The data is encrypted
        using the public key from the certificate provided during subscription creation.
      properties:
        data:
          type: string
          description: Base64-encoded encrypted data that, when decrypted, produces a JSON string conforming to the resource type indicated by dataType.
        dataSignature:
          type: string
          description: Base64-encoded HMAC-SHA256 hash of the data for validation purposes.
        dataKey:
          type: string
          description: Base64-encoded symmetric key generated by Microsoft Graph to encrypt the data value and to generate the data signature. This key is encrypted with the certificate public key provided
            during subscription creation.
        encryptionCertificateId:
          type: string
          description: The ID of the certificate used to encrypt the dataKey.
        encryptionCertificateThumbprint:
          type: string
          description: Base64-encoded thumbprint of the certificate used to encrypt the dataKey.
      required:
      - data
      - dataSignature
      - dataKey
      - encryptionCertificateId
      - encryptionCertificateThumbprint
    ValidationRequest:
      type: object
      description: Sent as a query parameter during subscription creation to validate the webhook endpoint. The endpoint must echo back the validationToken value as plain text in the response body.
      properties:
        validationToken:
          type: string
          description: A token string that the webhook endpoint must return in the response body as plain text to prove ownership of the notification URL.
      required:
      - validationToken
    LifecycleNotificationPayload:
      type: object
      description: A lifecycle notification payload informing the application about subscription management events. The lifecycleEvent property indicates the type of event, and the notification includes
        subscription identifiers for correlation.
      properties:
        value:
          type: array
          description: The set of lifecycle notifications in this payload.
          items:
            $ref: '#/components/schemas/LifecycleNotificationItem'
      required:
      - value
    LifecycleNotificationItem:
      type: object
      description: A single lifecycle notification item indicating a subscription state change that requires the application's attention.
      properties:
        id:
          type: string
          description: Unique identifier for this lifecycle notification.
        subscriptionId:
          type: string
          format: uuid
          description: The unique identifier of the affected subscription.
        subscriptionExpirationDateTime:
          type: string
          format: date-time
          description: The expiration date and time of the affected subscription.
        clientState:
          type: string
          maxLength: 128
          description: The clientState value from the subscription, for verification purposes.
        tenantId:
          type: string
          format: uuid
          description: The unique identifier of the originating Microsoft Entra tenant.
        lifecycleEvent:
          type: string
          description: The type of lifecycle event. Applications must handle each type to maintain reliable notification delivery.
          enum:
          - missed
          - subscriptionRemoved
          - reauthorizationRequired
        resource:
          type: string
          description: The URI of the resource associated with the subscription, relative to https://graph.microsoft.com.
        resourceData:
          $ref: '#/components/schemas/ResourceData'
      required:
      - subscriptionId
      - lifecycleEvent
      - tenantId
externalDocs:
  description: Microsoft Graph Change Notifications Documentation
  url: https://learn.microsoft.com/en-us/graph/change-notifications-overview