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: authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize 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