Microsoft Outlook Change Notifications

asyncapi: 3.0.0
info:
  title: Microsoft Outlook Change Notifications
  version: 1.0.0
  description: AsyncAPI specification for Microsoft Graph change notifications (webhooks) for Outlook
    mail resources. Enables real-time event-driven architecture by subscribing to changes in messages,
    mail folders, contacts, and calendar events through the Microsoft Graph subscriptions API.
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
  license:
    name: Microsoft API Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  externalDocs:
    description: Microsoft Graph Change Notifications Documentation
    url: https://learn.microsoft.com/en-us/graph/change-notifications-overview
  tags:
  - name: mail
    description: Change notifications for Outlook mail messages
  - name: webhooks
    description: Webhook-based push notifications
  - name: subscriptions
    description: Subscription management for change notifications
servers:
  graphApi:
    host: graph.microsoft.com
    pathname: /v1.0
    protocol: https
    description: Microsoft Graph v1.0 endpoint for creating and managing webhook subscriptions. Applications
      POST subscription requests to this server to register for change notifications.
    security:
    - $ref: '#/components/securitySchemes/oauth2'
  webhookEndpoint:
    host: '{webhookHost}'
    pathname: '{webhookPath}'
    protocol: https
    description: The application-provided HTTPS endpoint that receives change notification payloads from
      Microsoft Graph. Must be publicly accessible and respond to validation requests.
    variables:
      webhookHost:
        description: The hostname of your webhook receiver endpoint.
      webhookPath:
        description: The path of your webhook receiver endpoint.
channels:
  messageChanged:
    address: /me/messages
    title: Message Change Notifications
    description: Receives notifications when messages in the signed-in user's mailbox are created, updated,
      or deleted. Subscribe to this resource path via POST /subscriptions on the Microsoft Graph API.
    messages:
      messageChangeNotification:
        $ref: '#/components/messages/ChangeNotificationCollection'
    parameters:
      resource:
        description: The Microsoft Graph resource path being monitored.
        default: me/messages
  mailFolderChanged:
    address: /me/mailFolders
    title: Mail Folder Change Notifications
    description: Receives notifications when mail folders in the user's mailbox are created, updated,
      or deleted.
    messages:
      folderChangeNotification:
        $ref: '#/components/messages/ChangeNotificationCollection'
  userMailChanged:
    address: /users/{userId}/messages
    title: User Message Change Notifications (Application Permission)
    description: Receives notifications when messages in a specific user's mailbox are created, updated,
      or deleted. Requires application permissions (Mail.Read) rather than delegated permissions.
    parameters:
      userId:
        description: The unique identifier or UPN of the target user.
    messages:
      userMailChangeNotification:
        $ref: '#/components/messages/ChangeNotificationCollection'
  subscriptionLifecycle:
    address: /lifecycleNotifications
    title: Subscription Lifecycle Notifications
    description: Receives lifecycle events for subscriptions including missed notifications, subscription
      removal, and reauthorization requirements. Configure via the lifecycleNotificationUrl property on
      the subscription.
    messages:
      lifecycleNotification:
        $ref: '#/components/messages/LifecycleNotification'
operations:
  onMessageCreated:
    action: receive
    channel:
      $ref: '#/channels/messageChanged'
    title: Message Created
    summary: Triggered when a new message is created in the user's mailbox.
    description: A change notification is sent when a new message arrives in any folder of the subscribed
      mailbox. The notification includes the resource URI of the new message. Set changeType to "created"
      in the subscription.
    messages:
    - $ref: '#/channels/messageChanged/messages/messageChangeNotification'
  onMessageUpdated:
    action: receive
    channel:
      $ref: '#/channels/messageChanged'
    title: Message Updated
    summary: Triggered when a message is updated (e.g., marked as read, flagged, moved to a different
      folder).
    description: A change notification is sent when an existing message's properties change. Set changeType
      to "updated" in the subscription.
    messages:
    - $ref: '#/channels/messageChanged/messages/messageChangeNotification'
  onMessageDeleted:
    action: receive
    channel:
      $ref: '#/channels/messageChanged'
    title: Message Deleted
    summary: Triggered when a message is deleted from the user's mailbox.
    description: A change notification is sent when a message is soft-deleted (moved to Deleted Items)
      or hard-deleted. Set changeType to "deleted" in the subscription.
    messages:
    - $ref: '#/channels/messageChanged/messages/messageChangeNotification'
  onSubscriptionLifecycleEvent:
    action: receive
    channel:
      $ref: '#/channels/subscriptionLifecycle'
    title: Subscription Lifecycle Event
    summary: Triggered when a subscription lifecycle event occurs such as missed notifications or reauthorization
      required.
    messages:
    - $ref: '#/channels/subscriptionLifecycle/messages/lifecycleNotification'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: Microsoft identity platform OAuth 2.0 authorization for managing subscriptions and
        receiving change notifications.
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          availableScopes:
            Mail.Read: Read mail in all mailboxes (application permission)
            Mail.ReadWrite: Read and write mail in all mailboxes
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          availableScopes:
            Mail.Read: Read user mail (delegated)
            Mail.ReadWrite: Read and write access to user mail (delegated)
  messages:
    ChangeNotificationCollection:
      name: changeNotificationCollection
      title: Change Notification Collection
      summary: A collection of one or more change notifications delivered as a batch to the webhook endpoint
        via HTTP POST.
      description: Microsoft Graph delivers change notifications in batches. Each HTTP POST to your notification
        URL contains a JSON payload with a value array of changeNotification objects. Your endpoint must
        respond with HTTP 202 Accepted within 3 seconds.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ChangeNotificationCollectionPayload'
    LifecycleNotification:
      name: lifecycleNotification
      title: Lifecycle Notification
      summary: A lifecycle notification indicating a subscription state change.
      description: Lifecycle notifications inform the application about events like missed notifications,
        subscription removal due to policy, or reauthorization requirements. Delivered to the lifecycleNotificationUrl
        configured on the subscription.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/LifecycleNotificationPayload'
    SubscriptionValidation:
      name: subscriptionValidation
      title: Subscription Validation Request
      summary: Validation request sent by Microsoft Graph when creating a new subscription to verify the
        notification URL.
      description: When a subscription is created, Microsoft Graph sends a POST request to the notificationUrl
        with a validationToken query parameter. The endpoint must respond with HTTP 200 and the validationToken
        value as plain text in the response body within 10 seconds.
      contentType: text/plain
      payload:
        type: string
        description: The validation token that must be echoed back.
  schemas:
    ChangeNotificationCollectionPayload:
      type: object
      description: The top-level payload delivered to the webhook endpoint containing an array of change
        notifications.
      properties:
        value:
          type: array
          description: The collection of change notifications in this batch.
          items:
            $ref: '#/components/schemas/ChangeNotification'
      required:
      - value
    ChangeNotification:
      type: object
      description: Represents a single change notification sent to the subscriber application for a Microsoft
        Graph subscription.
      properties:
        id:
          type: string
          description: Unique identifier for the 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 in UTC.
        changeType:
          type: string
          enum:
          - created
          - updated
          - deleted
          description: The type of change that triggered the notification.
        clientState:
          type: string
          description: The value of the clientState property sent in the subscription request. Maximum
            255 characters. Use this to validate that the notification originated from Microsoft Graph.
        resource:
          type: string
          description: The URI of the resource that emitted the change notification, relative to https://graph.microsoft.com/v1.0.
          examples:
          - users/{userId}/messages/{messageId}
          - me/messages/{messageId}
        resourceData:
          $ref: '#/components/schemas/ResourceData'
        tenantId:
          type: string
          format: uuid
          description: The unique identifier of the Azure AD tenant.
        encryptedContent:
          $ref: '#/components/schemas/ChangeNotificationEncryptedContent'
      required:
      - subscriptionId
      - changeType
      - resource
      - subscriptionExpirationDateTime
      - tenantId
    ResourceData:
      type: object
      description: Properties of the resource that triggered the notification. The content depends on
        the resource type being subscribed to.
      properties:
        '@odata.type':
          type: string
          description: The OData entity type in Microsoft Graph of the resource.
          examples:
          - '#microsoft.graph.message'
        '@odata.id':
          type: string
          description: The OData identifier of the resource.
        '@odata.etag':
          type: string
          description: The HTTP entity tag representing the version of the resource.
        id:
          type: string
          description: The identifier of the resource.
    ChangeNotificationEncryptedContent:
      type: object
      description: Encrypted resource data attached with the change notification. Only provided if encryptionCertificate
        and includeResourceData were set on the subscription.
      properties:
        data:
          type: string
          description: Base64-encoded encrypted data producing a full JSON resource.
        dataSignature:
          type: string
          description: Base64-encoded HMAC-SHA256 hash of the data for validation.
        dataKey:
          type: string
          description: Base64-encoded symmetric key generated by Microsoft Graph to encrypt the data value
            and generate the data signature.
        encryptionCertificateId:
          type: string
          description: The ID of the certificate used to encrypt the dataKey.
        encryptionCertificateThumbprint:
          type: string
          description: Hexadecimal representation of the thumbprint of the certificate used to encrypt
            the dataKey.
    LifecycleNotificationPayload:
      type: object
      description: Payload for subscription lifecycle notifications.
      properties:
        value:
          type: array
          items:
            type: object
            properties:
              subscriptionId:
                type: string
                format: uuid
                description: The subscription that this lifecycle event relates to.
              subscriptionExpirationDateTime:
                type: string
                format: date-time
                description: The expiration date and time of the subscription.
              clientState:
                type: string
                description: The client state value from the subscription.
              tenantId:
                type: string
                format: uuid
                description: The Azure AD tenant identifier.
              resource:
                type: string
                description: The resource path of the subscription.
              lifecycleEvent:
                type: string
                enum:
                - missed
                - subscriptionRemoved
                - reauthorizationRequired
                description: The type of lifecycle event.
            required:
            - subscriptionId
            - lifecycleEvent
            - tenantId
    Subscription:
      type: object
      description: Represents a webhook subscription created via the Microsoft Graph subscriptions API.
        Applications create subscriptions to receive change notifications when data changes.
      properties:
        id:
          type: string
          description: Unique identifier for the subscription. Read-only.
          readOnly: true
        resource:
          type: string
          description: The resource that is monitored for changes. Do not include the base URL (https://graph.microsoft.com/v1.0/).
          examples:
          - me/messages
          - me/mailFolders('inbox')/messages
          - users/{id}/messages
        changeType:
          type: string
          description: The type of change in the subscribed resource that raises a notification. Multiple
            values can be combined with comma separation.
          examples:
          - created
          - updated
          - deleted
          - created,updated,deleted
        notificationUrl:
          type: string
          format: uri
          description: The HTTPS URL of the endpoint that receives change notifications.
        expirationDateTime:
          type: string
          format: date-time
          description: The date and time when the subscription expires in UTC. Maximum for Outlook messages
            is 4230 minutes (under 3 days). For rich notifications (includeResourceData=true), maximum
            is 1 day.
        clientState:
          type: string
          maxLength: 128
          description: A client-provided value included in each notification for validation. Maximum 128
            characters.
        lifecycleNotificationUrl:
          type: string
          format: uri
          description: The HTTPS URL that receives lifecycle notifications including subscriptionRemoved,
            reauthorizationRequired, and missed events.
        includeResourceData:
          type: boolean
          description: When true, change notifications include resource data (rich notifications). Requires
            encryptionCertificate.
        encryptionCertificate:
          type: string
          description: A base64-encoded certificate with a public key used to encrypt resource data in
            change notifications. Required when includeResourceData is true.
        encryptionCertificateId:
          type: string
          description: A custom identifier to help identify the decryption certificate.
        applicationId:
          type: string
          description: Identifier of the application used to create the subscription. Read-only.
          readOnly: true
        creatorId:
          type: string
          description: Identifier of the user or service principal that created the subscription. Read-only.
          readOnly: true
      required:
      - resource
      - changeType
      - notificationUrl
      - expirationDateTime