Microsoft Outlook · AsyncAPI Specification

Microsoft Outlook Change Notifications

Version 1.0.0

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.

View Spec View on GitHub CalendarContactsEmailEnterpriseMicrosoftOffice 365ProductivityAsyncAPIWebhooksEvents

Channels

messageChanged

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.

mailFolderChanged

Receives notifications when mail folders in the user's mailbox are created, updated, or deleted.

userMailChanged

Receives notifications when messages in a specific user's mailbox are created, updated, or deleted. Requires application permissions (Mail.Read) rather than delegated permissions.

subscriptionLifecycle

Receives lifecycle events for subscriptions including missed notifications, subscription removal, and reauthorization requirements. Configure via the lifecycleNotificationUrl property on the subscription.

Messages

✉

ChangeNotificationCollection

Change Notification Collection

A collection of one or more change notifications delivered as a batch to the webhook endpoint via HTTP POST.

✉

LifecycleNotification

Lifecycle Notification

A lifecycle notification indicating a subscription state change.

✉

SubscriptionValidation

Subscription Validation Request

Validation request sent by Microsoft Graph when creating a new subscription to verify the notification URL.

Servers

https

graphApi

Microsoft Graph v1.0 endpoint for creating and managing webhook subscriptions. Applications POST subscription requests to this server to register for change notifications.

https

webhookEndpoint

The application-provided HTTPS endpoint that receives change notification payloads from Microsoft Graph. Must be publicly accessible and respond to validation requests.