{"id":1601,"date":"2015-10-21T17:26:24","date_gmt":"2015-10-21T17:26:24","guid":{"rendered":"https:\/\/developer.microsoft.com\/en-us\/office\/blogs\/?p=1601"},"modified":"2015-10-21T17:26:24","modified_gmt":"2015-10-21T17:26:24","slug":"subscription-and-notification-schema-changes-in-beta-rest-api","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/subscription-and-notification-schema-changes-in-beta-rest-api\/","title":{"rendered":"Subscription and notification schema changes in beta REST API"},"content":{"rendered":"

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\u2019ll 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<\/a> for the current schema and functional behavior. Below are the details of each one.<\/p>\n

Schema changes<\/h2>\n

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

Subscription request<\/h3>\n

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.<\/p>\n\n\n\n\n\n\n\n\n
Current<\/th>\nInterim<\/th>\nFinal<\/th>\n<\/tr>\n
ResourceURL<\/code><\/td>\nresource<\/code><\/td>\nResource<\/code><\/td>\n<\/tr>\n
CallbackURL<\/code><\/td>\nnotificationURL<\/code><\/td>\nNotificationURL<\/code><\/td>\n<\/tr>\n
ClientState<\/code><\/td>\ncontext<\/code><\/td>\nClientState<\/code><\/td>\n<\/tr>\n
ExpirationTime<\/code><\/td>\nsubscriptionExpirationDateTime<\/code><\/td>\nSubscriptionExpirationDateTime<\/code><\/td>\n<\/tr>\n
ChangeType<\/code><\/td>\nchangeType<\/code><\/td>\nChangeType<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Subscription sample<\/h3>\n

Final version (changes highlighted)<\/strong><\/p>\n

 {\n \u00a0\u00a0@odata.type:\"#Microsoft.OutlookServices.PushSubscription\",\n \u00a0\u00a0Resource: \"https:\/\/outlook.office.com\/api\/beta\/me\/folders('Inbox')\/messages\",\n \u00a0\u00a0NotificationURL: \"https:\/\/webhook.azurewebsites.net\/api\/send\/rest_notify\",\n \u00a0\u00a0ChangeType: \"Created, Updated, Deleted\",\n \u00a0\u00a0SubscriptionExpirationDateTime: \"2015-10-24T18:40:00.0Z\",\n \u00a0\u00a0ClientState: \"Client information\"\n } <\/code><\/pre>\n
Interim version (changes highlighted)<\/strong><\/p>\n
 { \u00a0\u00a0@odata.type:\"#Microsoft.OutlookServices.PushSubscription\",\n \u00a0\u00a0resource: \"https:\/\/outlook.office.com\/api\/beta\/me\/folders('Inbox')\/messages\",\n \u00a0\u00a0notificationURL: \"https:\/\/webhook.azurewebsites.net\/api\/send\/rest_notify\",\n \u00a0\u00a0changeType: \"Created, Updated, Deleted\",\n \u00a0\u00a0subscriptionExpirationDateTime: \"2015-10-24T18:40:00.0Z\",\n \u00a0\u00a0context: \"Client information\"\n } <\/code><\/pre>\n
Notification payload<\/h3>\n
The following property was added to the notification body.<\/p>\n\n\n\n\n
Interim<\/th>\nFinal<\/th>\n<\/tr>\n
resource<\/code><\/td>\nResource<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
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<\/strong><\/p>\n\n\n\n\n
Current name<\/th>\nInterim name<\/th>\nFinal name<\/th>\n<\/tr>\n
x-ClientState<\/code><\/td>\nx-context<\/td>\nClientState<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Body<\/strong><\/p>\n\n\n\n\n\n\n\n\n
Current name<\/th>\nInterim name<\/th>\nFinal name<\/th>\n<\/tr>\n
Entity<\/code><\/td>\nresourceData<\/code><\/td>\nResourceData<\/code><\/td>\n<\/tr>\n
SubscriptionExpirationTime<\/code><\/td>\nsubscriptionExpirationDateTime<\/code><\/td>\nSubscriptionExpirationDateTime<\/code><\/td>\n<\/tr>\n
SubscriptionId<\/code>*<\/td>\nsubscriptionId<\/code><\/td>\nSubscriptionId<\/code><\/td>\n<\/tr>\n
SequenceNumber<\/code>*<\/td>\nsequenceNumber<\/code><\/td>\nSequenceNumber<\/code><\/td>\n<\/tr>\n
ChangeType<\/code>*<\/td>\nchangeType<\/code><\/td>\nChangeType<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
*<\/strong> indicates lowerCamelCase type change in the interim version<\/p><\/blockquote>\n
Notification sample<\/h3>\n
Final version (changes highlighted)<\/strong><\/p>\n
 ClientState: Client information\n OData-Version: 4.0\n \n {\n \u00a0\u00a0\"value\": [\n \u00a0\u00a0\u00a0\u00a0{\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.type\": \"#Microsoft.OutlookServices.Notification\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"Id\": null,\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"SubscriptionId\": \"Y3BENzI2MEMtODNDOS00OTgwLUI4MzYtRkU0RkJFQ0QwNDA0XzI0MjlFMDM3LTIyODAtNDI5QS05RTI5LTQ2ODJEMjUxNDFENg==\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"SubscriptionExpirationDateTime\": \"2015-10-24T18:40:00Z\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"SequenceNumber\": 1,\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ChangeType\": \"Created\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"Resource\": \"https:\/\/outlook.office.com\/api\/beta\/Users('user@contoso.com')\/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ResourceData\": {\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.type\": \"#Microsoft.OutlookServices.Message\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.id\": \"https:\/\/outlook.office.com\/api\/beta\/Users('user@contoso.com')\/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.etag\": \"W\/\\\"CQAAABYAAADEtR7gR4I6QrDE5OwdwwziAAAAAAT1\\\"\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"Id\": \"AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==\"\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0}\n \u00a0\u00a0\u00a0\u00a0}\n \u00a0\u00a0]\n } <\/code><\/pre>\n
Interim version (changes highlighted)<\/strong><\/p>\n
 x-context: Client information\n OData-Version: 4.0\n \n {\n \u00a0\u00a0\"value\": [\n \u00a0\u00a0\u00a0\u00a0{\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.type\": \"#Microsoft.OutlookServices.Notification\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"Id\": null,\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"subscriptionId\": \"Y3BENzI2MEMtODNDOS00OTgwLUI4MzYtRkU0RkJFQ0QwNDA0XzI0MjlFMDM3LTIyODAtNDI5QS05RTI5LTQ2ODJEMjUxNDFENg==\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"subscriptionExpirationDateTime\": \"2015-10-24T18:40:00Z\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"sequenceNumber\": 1,\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"changeType\": \"Created\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"resource\": \"https:\/\/outlook.office.com\/api\/beta\/Users('user@contoso.com')\/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"resourceData\": {\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.type\": \"#Microsoft.OutlookServices.Message\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.id\": \"https:\/\/outlook.office.com\/api\/beta\/Users('user@contoso.com')\/Messages('AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==')\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"@odata.etag\": \"W\/\\\"CQAAABYAAADEtR7gR4I6QrDE5OwdwwziAAAAAAT1\\\"\",\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"Id\": \"AQMkADI0MjllMDM3LTIyADgwLTQyOWEtOWUyOS00NjgyZDI1MTQxZDYARgAAA8rN0_5DrtJIjeiZuFmXzhwHAMS1HuBHgjpCsMTk7B3DDOIAAAIBDAAAAMS1HuBHgjpCsMTk7B3DDOIAAAIFeQAAAA==\"\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0}\n \u00a0\u00a0\u00a0\u00a0}\n \u00a0\u00a0]\n } <\/code><\/pre>\n
Functional changes<\/h2>\n
There are four breaking functional changes in Beta. These changes are:<\/p>\n
    \n
  1. Changes in Renew subscription API<\/li>\n
  2. Addition of Notification URL validation<\/li>\n
  3. Retiring Acknowledgement notification<\/li>\n
  4. No ClientState<\/code> in Subscription query response<\/li>\n<\/ol>\n
    Not all changes apply to the interim. Here is the functional change applicability matrix (final versus interim):<\/p>\n\n\n\n\n\n\n\n
    Functional change<\/th>\nInterim<\/th>\nFinal<\/th>\n<\/tr>\n
    Changes in Renew subscription API<\/td>\nYes<\/td>\nYes<\/td>\n<\/tr>\n
    Addition of Notification URL validation<\/td>\nNo<\/td>\nYes<\/td>\n<\/tr>\n
    Retiring Acknowledgement notification<\/td>\nNo<\/td>\nYes<\/td>\n<\/tr>\n
    No ClientState<\/code> in Subscription query response<\/td>\nYes<\/td>\nYes<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Changes in Renew subscription API<\/h3>\n
    The renew subscription mechanism changed from POST to PATCH with payload like the following. Final version<\/strong><\/p>\n
     {\n \u00a0\u00a0@odata.type:\"#Microsoft.OutlookServices.PushSubscription\",\n \u00a0\u00a0SubscriptionExpirationDateTime: \"2015-10-24T20:00:00.0Z\"\n } <\/code><\/pre>\n
    Interim version<\/strong><\/p>\n
     {\n \u00a0\u00a0\u00a0\u00a0@odata.type:\"#Microsoft.OutlookServices.PushSubscription\",\n \u00a0\u00a0\u00a0\u00a0subscriptionExpirationDateTime: \"2015-10-24T20:00:00.0Z\"\n } <\/code><\/pre>\n
    Addition of Notification URL validation<\/h3>\n
    Outlook REST APIs added validation for notification (callback) URL as part of creating a new subscription. Validation occurs as follows:<\/p>\n
      \n
    1. Outlook service post the following to webhook service:\n
       POST https:\/\/<notificationUrl>?validationtoken=<TokenDefinedByService>\n \n ClientState: <Data sent in ClientState value in subscription request (if any)> <\/code><\/pre>\n<\/li>\n
    2. Webhooks service must provide a 200 response with the validationtoken<\/code> value in its body as type plain\/text<\/code> within 5 seconds. The validation token is a random string that should be discarded by the webhook after providing it in the response.<\/li>\n<\/ol>\n
      Retiring Acknowledgement notification<\/h3>\n
      The notification URL validation process is replacing the acknowledgement notification.<\/p>\n
      No ClientState in Subscription query response<\/h3>\n
      The ClientState<\/code> (or context<\/code> 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<\/a> for the latest news and updates.<\/p>\n
      This post was a guest post from Abdelkader Bahgat, a Senior Program Manager with the Outlook team.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"
      We 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.<\/p>\n","protected":false},"author":69077,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[12],"class_list":["post-1601","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","tag-outlook"],"acf":[],"blog_post_summary":"
      We 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.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1601","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69077"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=1601"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1601\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=1601"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=1601"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=1601"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}