I wanted to update you all on some more breaking changes that we are making to the Outlook REST API beta endpoint. These changes impact Notifications and Webhooks. They are going to be deployed worldwide in phases over the next few weeks. Since this deployment is going in phases, you may see up to two breaking changes for some of the APIs. In this blog, I’ll provide the final state of every change as well as its corresponding interim state (if applicable) during the phased rollout. There are two type of changes; schema changes and functional changes. Refer to the notification reference documentation for the current schema and functional behavior. Below are the details of each one.

Schema changes

Schema changes apply to both subscription requests and notification payloads as follows. Also they apply to both https://outlook.office.com/api/beta and https://outlook.office365.com/api/beta endpoints.

Subscription request

The following subscription properties were updated as part of the breaking change. The table below shows the current property name, interim name and final name.

Subscription sample

Final version (changes highlighted)

 {
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   Resource: "https://outlook.office.com/api/beta/me/folders('Inbox')/messages",
   NotificationURL: "https://webhook.azurewebsites.net/api/send/rest_notify",
   ChangeType: "Created, Updated, Deleted",
   SubscriptionExpirationDateTime: "2015-10-24T18:40:00.0Z",
   ClientState: "Client information"
 } 

Interim version (changes highlighted)

 {   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   resource: "https://outlook.office.com/api/beta/me/folders('Inbox')/messages",
   notificationURL: "https://webhook.azurewebsites.net/api/send/rest_notify",
   changeType: "Created, Updated, Deleted",
   subscriptionExpirationDateTime: "2015-10-24T18:40:00.0Z",
   context: "Client information"
 } 

Notification payload

The following property was added to the notification body.

The following notification properties were updated as part of the breaking change. The table below shows the current property name, interim name and final name. Header

Body

* indicates lowerCamelCase type change in the interim version

Notification sample

Final version (changes highlighted)

 ClientState: Client information
 OData-Version: 4.0
 
 {
   "value": [
     {
       "@odata.type": "#Microsoft.OutlookServices.Notification",
       "Id": null,
       "SubscriptionId": "Y3BENzI2MEMtODNDOS00OTgwLUI4MzYtRkU0RkJFQ0QwNDA0XzI0MjlFMDM3LTIyODAtNDI5QS05RTI5LTQ2ODJEMjUxNDFENg==",
       "SubscriptionExpirationDateTime": "2015-10-24T18:40:00Z",
       "SequenceNumber": 1,
       "ChangeType": "Created",
       "Resource": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
       "ResourceData": {
         "@odata.type": "#Microsoft.OutlookServices.Message",
         "@odata.id": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
         "@odata.etag": "W/\"CQAAABYAAADEtR7gR4I6QrDE5OwdwwziAAAAAAT1\"",
         "Id": "AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA=="
       }
     }
   ]
 } 

Interim version (changes highlighted)

 x-context: Client information
 OData-Version: 4.0
 
 {
   "value": [
     {
       "@odata.type": "#Microsoft.OutlookServices.Notification",
       "Id": null,
       "subscriptionId": "Y3BENzI2MEMtODNDOS00OTgwLUI4MzYtRkU0RkJFQ0QwNDA0XzI0MjlFMDM3LTIyODAtNDI5QS05RTI5LTQ2ODJEMjUxNDFENg==",
       "subscriptionExpirationDateTime": "2015-10-24T18:40:00Z",
       "sequenceNumber": 1,
       "changeType": "Created",
       "resource": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
       "resourceData": {
         "@odata.type": "#Microsoft.OutlookServices.Message",
         "@odata.id": "https://outlook.office.com/api/beta/Users('user@contoso.com')/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')",
         "@odata.etag": "W/\"CQAAABYAAADEtR7gR4I6QrDE5OwdwwziAAAAAAT1\"",
         "Id": "AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA=="
       }
     }
   ]
 } 

Functional changes

There are four breaking functional changes in Beta. These changes are:

1. Changes in Renew subscription API
2. Addition of Notification URL validation
3. Retiring Acknowledgement notification
4. No ClientState in Subscription query response

Not all changes apply to the interim. Here is the functional change applicability matrix (final versus interim):

Changes in Renew subscription API

The renew subscription mechanism changed from POST to PATCH with payload like the following. Final version

 {
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   SubscriptionExpirationDateTime: "2015-10-24T20:00:00.0Z"
 } 

Interim version

 {
     @odata.type:"#Microsoft.OutlookServices.PushSubscription",
     subscriptionExpirationDateTime: "2015-10-24T20:00:00.0Z"
 } 

Addition of Notification URL validation

Outlook REST APIs added validation for notification (callback) URL as part of creating a new subscription. Validation occurs as follows:

1. Outlook service post the following to webhook service:

    POST https://<notificationUrl>?validationtoken=<TokenDefinedByService>
    
    ClientState: <Data sent in ClientState value in subscription request (if any)> 

2. Webhooks service must provide a 200 response with the validationtoken value in its body as type plain/text within 5 seconds. The validation token is a random string that should be discarded by the webhook after providing it in the response.

Retiring Acknowledgement notification

The notification URL validation process is replacing the acknowledgement notification.

No ClientState in Subscription query response

The ClientState (or context in interim state) property is not going to be sent back when a client queries for a specific subscription. More extensive documentation on the new functionality is coming soon in our API reference documentation page. Please let us know if you have any questions, and visit http://dev.outlook.com for the latest news and updates.

This post was a guest post from Abdelkader Bahgat, a Senior Program Manager with the Outlook team.