Merge branch 'staging' of https://github.com/SharePoint/sp-dev-docs into staging

Author: suramam

docs/apis/webhooks/get-started-webhooks.md

@@ -1,21 +1,24 @@
 # Create a new subscription 
-Creates a new subscription. In the POST request, include properties to describe the subscription you want created.
+
+>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
+
+Creates a new webhook subscription on a SharePoint list. 
 
 ## Permissions
 
 The application must have at least edit permissions to the SharePoint list where the subscription will be created.
 
-**If your application is an Azure Active Directory (AAD) application:**
+**If your application is a Microsoft Azure Active Directory (AD) application:**
 
-You must grant the AAD app permissions to the folowing SharePoint application and the corresponding permissions:
+You must grant the Azure AD app the permissions specified in the following table:
 
 Application | Permission 
 ------------|------------
-Office 365 SharePoint Online|read and write items and lists in all site collections.
+Office 365 SharePoint Online|Read and write items and lists in all site collections.
 
 **If your application is a SharePoint add-in:**
 
-You must grant the add-in at least the following permission(s) or higher:
+You must grant the SharePoint add-in the following permission(s) or higher:
 
 Scope | Permission Rights 
 ------|------------
@@ -28,14 +31,15 @@ POST /_api/web/lists('list-id')/subscriptions
 ```
 
 ## Request body
+
 Include the following properties in the request body.
 
 Name | Type | Description 
 -----|------|------------
 resource|string|The URL of the list to receive notifications from.
 notificationUrl|string|The service URL to send notifications to.
 expirationDateTime|date|The date the notification will expire and be deleted.
-client-clientState|string|Optional. Opaque string passed back to the client on all notifications. You can use this for validating notificaitons, or tagging different subscriptions.
+client-clientState|string|Optional. Opaque string passed back to the client on all notifications. You can use this for validating notifications, or tagging different subscriptions.
 
 
 ### Example
@@ -53,6 +57,7 @@ Content-Type: application/json
 ```
 
 ## Response
+
 If the subscription is added, then a `201 Created` response is returned that
 includes the newly created subscription object.
 
@@ -71,6 +76,7 @@ Content-Type: application/json
 ```
 
 ## URL validation
+
 Before a new subscription is created, SharePoint will send a request with a validation token in the body of the request to the service URL provided. Your service must respond to this request by returning the validation token.
 
-If your service fails to validate the request in this way, the subscription will not be created. See [SharePoint list webhooks](../overview-sharepoint-webhooks.md) for more information.
+If your service fails to validate the request in this way, the subscription will not be created. See [Overview of SharePoint webhooks](../overview-sharepoint-webhooks) for more information.

docs/apis/webhooks/lists/create-subscription.md

@@ -1,11 +1,28 @@
 # Delete a subscription
 
+>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
+
 Deletes a webhook subscription from a SharePoint list. After deleting the subscription notifications will no longer be delivered.
 
 ## Permissions
 
-* A subscription can only be deleted by the application that created it. 
-* To delete a subscription the application must have **read-write permissions** to the SharePoint list the subscription exists on.
+The application must have at least edit permissions to the SharePoint list where the subscription will be deleted.
+
+**If your application is a Microsoft Azure Active Directory (AD) application:**
+
+You must grant the Azure AD app the permissions specified in the following table. A subscription can only be deleted by the Azure AD application that created it.
+
+Application | Permission 
+------------|------------
+Office 365 SharePoint Online|Read and write items and lists in all site collections.
+
+**If your application is a SharePoint add-in:**
+
+You must grant the SharePoint add-in the following permission(s) or higher. A subscription can only be deleted by the SharePoint add-in that created it.
+
+Scope | Permission Rights 
+------|------------
+List|Manage
 
 ## HTTP request
 
@@ -20,6 +37,7 @@ DELETE _api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions('6D7
 ```
 
 ## Request body
+
 Do not supply a request body for this method.
 
 ## Response
@@ -30,4 +48,4 @@ If the subscription is found and successfully deleted, then a `204 No Content` r
 
 ```http
 HTTP/1.1 204 No Content
-```
+```

docs/apis/webhooks/lists/delete-subscription.md

@@ -1,17 +1,50 @@
 # Get subscriptions
 
+>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
+
 Gets one or more webhook subscriptions on a SharePoint list.
 
 ## Permissions
 
 ### Get a single subscription
 
-* A subscription can only be retrieved by the application that created it. 
-* To get subscriptions, your application must have the **read-write permissions** to the SharePoint list where the subscriptions exist. 
+The application must have at least edit permissions to the SharePoint list where the subscription will be retreived.
+
+**If your application is a Microsoft Azure Active Directory (AD) application:**
+
+You must grant the Azure AD application the permissions specified in the following table. A subscription can only be retrieved by the Azure AD application that created it. 
+
+Application | Permission 
+------------|------------
+Office 365 SharePoint Online|Read and write items and lists in all site collections.
+
+**If your application is a SharePoint add-in:**
+
+You must grant the SharePoint add-in the following permission(s) or higher. A subscription can only be retrieved by the SharePoint add-in that created it. 
+
+Scope | Permission Rights 
+------|------------
+List|Manage
 
 ### Get all subscriptions
 
-* To get all subscriptions on a SharePoint list, your application must have the **manage lists permissions** on the SharePoint list where the subscriptions exist. 
+The application must have manage list permissions to the SharePoint list where the subscription will be retrieved.
+
+**If your application is a Microsoft Azure Active Directory (AD) application:**
+
+You must grant the Azure AD app the permissions specified in the following table. 
+
+Application | Permission 
+------------|------------
+Office 365 SharePoint Online|Have full control of all site collections.
+
+**If your application is a SharePoint add-in:**
+
+You must grant the SharePoint add-in the following permission(s) or higher. 
+
+Scope | Permission Rights 
+------|------------
+List|Full control
 
 ## HTTP request
 
@@ -29,9 +62,11 @@ GET _api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions('6D7703
 ```
 
 #### Request body
+
 Do not supply a request body for this method.
 
 ##### Response
+
 This returns the subscription viewable by the calling application.
 
 ```http
@@ -64,6 +99,7 @@ GET _api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions
 ```
 
 #### Request body
+
 Do not supply a request body for this method.
 
 ##### Response

docs/apis/webhooks/lists/get-subscription.md

@@ -1,32 +1,34 @@
 # SharePoint list webhooks
 
+>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
+
 The SharePoint list webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint webhooks provide a simple notification pipeline so your application can be aware of changes to a SharePoint list without polling the service.
 
-## Common tasks
+## Tasks
 | Task                                                | HTTP method                                                  |
 |-----------------------------------------------------|--------------------------------------------------------------|
 | [Create a new subscription](./create-subscription) | `POST    /_api/web/lists('list-guid')/subscriptions`         |
-| [Get subscription(s)](./get-subscription)          | `GET     /_api/web/lists('list-guid')/subscriptions`         |
-| [Delete subscription](./delete-subscription)       | `DELETE  /_api/web/lists('list-guid')/subscriptions('id')`   |
+| [Get subscriptions](./get-subscription)          | `GET     /_api/web/lists('list-guid')/subscriptions`         |
+| [Delete a subscription](./delete-subscription)       | `DELETE  /_api/web/lists('list-guid')/subscriptions('id')`   |
 | [Update a subscription](./update-subscription)     | `PATCH   /_api/web/lists('list-guid')/subscriptions('id')`   |
 
 ## List event types
-Notifications will be sent to your application for the following **asynchronous list item events** in SharePoint:
-
-1.	ItemAdded
-2.	ItemUpdated
-3.	ItemDeleted
-4.	ItemCheckedOut
-5.	ItemCheckedIn
-6.	ItemUncheckedOut
-7.	ItemAttachmentAdded
-8.	ItemAtttachmentDeleted
-9.	ItemFileMoved
-10.	ItemVersonDeleted
-11.	ItemFileConverted
+Notifications will be sent to your application for the following asynchronous list item events in SharePoint:
+
+* ItemAdded
+* ItemUpdated
+* ItemDeleted
+* ItemCheckedOut
+* ItemCheckedIn
+* ItemUncheckedOut
+* ItemAttachmentAdded
+* ItemAtttachmentDeleted
+* ItemFileMoved
+* ItemVersonDeleted
+* ItemFileConverted
 
 Synchronous events are not supported in webhooks.
 
 ## Additional resources
 
-- [Overview of SharePoint webhooks](../sharepoint-webhooks-overview)
+* [Overview of SharePoint webhooks](../overview-sharepoint-webhooks)

docs/apis/webhooks/lists/overview-sharepoint-list-webhooks.md

@@ -1,22 +1,24 @@
 # Update a subscription
 
+>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
+
 Updates a webhook subscription on a SharePoint list.
 
 ## Permissions
 
-The application must have at least edit permissions to the SharePoint list where the subscription will be created.  
+The application must have at least edit permissions to the SharePoint list where the subscription will be updated.  
 
-**If your application is an Azure Active Directory (AAD) application:**
+**If your application is an Microsoft Azure Active Directory (AD) application:**
 
-You must grant the AAD app permissions to the folowing SharePoint application and the corresponding permissions. A subscription can only be updated by the AAD application that created it.
+You must grant the Azure AD application the permissions specified in the following table. A subscription can only be updated by the Azure AD application that created it.
 
 Application | Permission 
 ------------|------------
-Office 365 SharePoint Online|read and write items and lists in all site collections. 
+Office 365 SharePoint Online|Read and write items and lists in all site collections. 
 
 **If your application is a SharePoint add-in:**
 
-You must grant the add-in at least the following permission(s) or higher. A subscription can only be updated by the add-in that created it.
+You must grant the SharePoint add-in the following permission(s) or higher. A subscription can only be updated by the SharePoint add-in that created it.
 
 Scope | Permission Rights 
 ------|------------
@@ -41,13 +43,14 @@ Content-Type: application/json
 ```
 
 ## Request body
+
 Include the following properties in the request body.
 
 Name | Type | Description 
 -----|------|------------
 notificationUrl|string|The service URL to send notifications to.
 expirationDateTime|date|The date the notification will expire and be deleted.
-client-clientState|string|Optional. Opaque string passed back to the client on all notifications. You can use this for validating notificaitons, or tagging different subscriptions.
+client-clientState|string|Optional. Opaque string passed back to the client on all notifications. You can use this for validating notifications, or tagging different subscriptions.
 
 
 ## Response