Skip to content

Commit 674c439

Browse files
chakkaradeepchakkaradeep
authored
Merge pull request SharePoint#171 from SharePoint/staging
Webhooks docs release
2 parents 3bb85ad + af51c2d commit 674c439

34 files changed

+1210
-23
lines changed

‎.github/ISSUE_TEMPLATE.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ Thank you for reporting an issue or suggesting an enhancement. We appreciate you
33
#### Category
44
[ ] Question
55
[ ] Typo
6-
[ ] Mistake
6+
[ ] Bug
7+
[ ] Enhancement / Suggestion
78
[ ] Additional article idea
89

910
#### Expected or Desired Behavior

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

Lines changed: 472 additions & 0 deletions
Large diffs are not rendered by default.

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Create a new subscription
2+
3+
>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
4+
5+
Creates a new webhook subscription on a SharePoint list.
6+
7+
## Permissions
8+
9+
The application must have at least edit permissions to the SharePoint list where the subscription will be created.
10+
11+
**If your application is a Microsoft Azure Active Directory (AD) application:**
12+
13+
You must grant the Azure AD app the permissions specified in the following table:
14+
15+
Application | Permission
16+
------------|------------
17+
Office 365 SharePoint Online|Read and write items and lists in all site collections.
18+
19+
**If your application is a SharePoint add-in:**
20+
21+
You must grant the SharePoint add-in the following permission(s) or higher:
22+
23+
Scope | Permission Rights
24+
------|------------
25+
List|Manage
26+
27+
## HTTP request
28+
29+
```
30+
POST /_api/web/lists('list-id')/subscriptions
31+
```
32+
33+
## Request body
34+
35+
Include the following properties in the request body.
36+
37+
Name | Type | Description
38+
-----|------|------------
39+
resource|string|The URL of the list to receive notifications from.
40+
notificationUrl|string|The service URL to send notifications to.
41+
expirationDateTime|date|The date the notification will expire and be deleted.
42+
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.
43+
44+
45+
### Example
46+
47+
```http
48+
POST /_api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions
49+
Accept: application/json
50+
Content-Type: application/json
51+
52+
{
53+
"resource": "https://contoso.sharepoint.com/_api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')",
54+
"notificationUrl": "https://91e383a5.ngrok.io/api/webhook/handlerequest",
55+
"expirationDateTime": "2016-04-27T16:17:57+00:00"
56+
}
57+
```
58+
59+
## Response
60+
61+
If the subscription is added, then a `201 Created` response is returned that
62+
includes the newly created subscription object.
63+
64+
### Example
65+
66+
```http
67+
HTTP/1.1 201 Created
68+
Content-Type: application/json
69+
70+
{
71+
"id": "a8e6d5e6-9f7f-497a-b97f-8ffe8f559dc7",
72+
"expirationDateTime": "2016-04-27T16:17:57Z",
73+
"notificationUrl": "https://91e383a5.ngrok.io/api/webhook/handlerequest",
74+
"resource": "5c77031a-9621-4dfc-bb5d-57803a94e91d"
75+
}
76+
```
77+
78+
## URL validation
79+
80+
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.
81+
82+
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/delete-subscription.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Delete a subscription
2+
3+
>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
4+
5+
Deletes a webhook subscription from a SharePoint list. After deleting the subscription notifications will no longer be delivered.
6+
7+
## Permissions
8+
9+
The application must have at least edit permissions to the SharePoint list where the subscription will be deleted.
10+
11+
**If your application is a Microsoft Azure Active Directory (AD) application:**
12+
13+
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.
14+
15+
Application | Permission
16+
------------|------------
17+
Office 365 SharePoint Online|Read and write items and lists in all site collections.
18+
19+
**If your application is a SharePoint add-in:**
20+
21+
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.
22+
23+
Scope | Permission Rights
24+
------|------------
25+
List|Manage
26+
27+
## HTTP request
28+
29+
```
30+
DELETE _api/web/lists('list-id')/subscriptions('id')
31+
```
32+
33+
### Example
34+
35+
```http
36+
DELETE _api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions('6D77031A-2345-5GRT-BV3D-55234B56FR43')
37+
```
38+
39+
## Request body
40+
41+
Do not supply a request body for this method.
42+
43+
## Response
44+
45+
If the subscription is found and successfully deleted, then a `204 No Content` response is returned.
46+
47+
### Example
48+
49+
```http
50+
HTTP/1.1 204 No Content
51+
```

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

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Get subscriptions
2+
3+
>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
4+
5+
Gets one or more webhook subscriptions on a SharePoint list.
6+
7+
## Permissions
8+
9+
### Get a single subscription
10+
11+
The application must have at least edit permissions to the SharePoint list where the subscription will be retreived.
12+
13+
**If your application is a Microsoft Azure Active Directory (AD) application:**
14+
15+
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.
16+
17+
Application | Permission
18+
------------|------------
19+
Office 365 SharePoint Online|Read and write items and lists in all site collections.
20+
21+
**If your application is a SharePoint add-in:**
22+
23+
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.
24+
25+
Scope | Permission Rights
26+
------|------------
27+
List|Manage
28+
29+
### Get all subscriptions
30+
31+
The application must have manage list permissions to the SharePoint list where the subscription will be retrieved.
32+
33+
**If your application is a Microsoft Azure Active Directory (AD) application:**
34+
35+
You must grant the Azure AD app the permissions specified in the following table.
36+
37+
Application | Permission
38+
------------|------------
39+
Office 365 SharePoint Online|Have full control of all site collections.
40+
41+
**If your application is a SharePoint add-in:**
42+
43+
You must grant the SharePoint add-in the following permission(s) or higher.
44+
45+
Scope | Permission Rights
46+
------|------------
47+
List|Full control
48+
49+
## HTTP request
50+
51+
### Get a single subscription
52+
53+
#### List webhook
54+
```
55+
GET _api/web/lists('list-id')/subscriptions('id')
56+
```
57+
58+
##### Example
59+
60+
```http
61+
GET _api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions('6D77031A-2345-5GRT-BV3D-55234B56FR43')
62+
```
63+
64+
#### Request body
65+
66+
Do not supply a request body for this method.
67+
68+
##### Response
69+
70+
This returns the subscription viewable by the calling application.
71+
72+
```http
73+
HTTP/1.1 200 OK
74+
Content-Type: application/json
75+
76+
{
77+
"odata.metadata": "https://contoso.sharepoint.com/_api/$metadata#SP.ApiData.Subscriptions/@Element",
78+
"odata.type": "Microsoft.SharePoint.Webhooks.Subscription",
79+
"odata.id": "https://contoso.sharepoint.com/_api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions('a8e6d5e6-9f7f-497a-b97f-8ffe8f559dc7')",
80+
"odata.editLink": "web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions('a8e6d5e6-9f7f-497a-b97f-8ffe8f559dc7')",
81+
"expirationDateTime": "2016-04-30T16:17:57Z",
82+
"id": "a8e6d5e6-9f7f-497a-b97f-8ffe8f559dc7",
83+
"notificationUrl": "https://contoso.azurewebistes.net/api/webhook/handlerequest",
84+
"resource": "5c77031a-9621-4dfc-bb5d-57803a94e91d"
85+
}
86+
```
87+
88+
### Get all subscriptions
89+
90+
#### List webhook
91+
```
92+
GET _api/web/lists('list-id')/subscriptions
93+
```
94+
95+
##### Example
96+
97+
```http
98+
GET _api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions
99+
```
100+
101+
#### Request body
102+
103+
Do not supply a request body for this method.
104+
105+
##### Response
106+
107+
This returns a collection of all subscriptions on a SharePoint resource.
108+
109+
```http
110+
HTTP/1.1 200 OK
111+
Content-Type: application/json
112+
113+
{
114+
"odata.metadata": "https://a830edad9050849295j16032914.sharepoint.com/_api/$metadata#SP.ApiData.Subscriptions",
115+
"value": [
116+
{
117+
"odata.type": "Microsoft.SharePoint.Webhooks.Subscription",
118+
"odata.id": "https://contoso.sharepoint.com/_api/Microsoft.SharePoint.Webhooks.Subscriptionc3175b9c-1491-454f-b5da-980431e36146",
119+
"odata.editLink": "Microsoft.SharePoint.Webhooks.Subscriptionc3175b9c-1491-454f-b5da-980431e36146",
120+
"clientState": "{A0A354EC-97D4-4D83-9DDB-144077ADB449}",
121+
"expirationDateTime": "2016-04-30T16:17:57Z",
122+
"id": "a8e6d5e6-9f7f-497a-b97f-8ffe8f559dc7",
123+
"notificationUrl": "https://contoso.azurewebsites.net/api/webhook/handlerequest",
124+
"resource": "5c77031a-9621-4dfc-bb5d-57803a94e91d"
125+
}
126+
]
127+
}
128+
```

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# SharePoint list webhooks
2+
3+
>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
4+
5+
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.
6+
7+
## Tasks
8+
| Task | HTTP method |
9+
|-----------------------------------------------------|--------------------------------------------------------------|
10+
| [Create a new subscription](./create-subscription) | `POST /_api/web/lists('list-guid')/subscriptions` |
11+
| [Get subscriptions](./get-subscription) | `GET /_api/web/lists('list-guid')/subscriptions` |
12+
| [Delete a subscription](./delete-subscription) | `DELETE /_api/web/lists('list-guid')/subscriptions('id')` |
13+
| [Update a subscription](./update-subscription) | `PATCH /_api/web/lists('list-guid')/subscriptions('id')` |
14+
15+
## List event types
16+
Notifications will be sent to your application for the following asynchronous list item events in SharePoint:
17+
18+
* ItemAdded
19+
* ItemUpdated
20+
* ItemDeleted
21+
* ItemCheckedOut
22+
* ItemCheckedIn
23+
* ItemUncheckedOut
24+
* ItemAttachmentAdded
25+
* ItemAtttachmentDeleted
26+
* ItemFileMoved
27+
* ItemVersonDeleted
28+
* ItemFileConverted
29+
30+
Synchronous events are not supported in webhooks.
31+
32+
## Additional resources
33+
34+
* [Overview of SharePoint webhooks](../overview-sharepoint-webhooks)

‎docs/apis/webhooks/lists/update-subscription.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Update a subscription
2+
3+
>**Note:** SharePoint webhooks is currently in preview and is subject to change. SharePoint webhooks are not currently supported for use in production environments.
4+
5+
Updates a webhook subscription on a SharePoint list.
6+
7+
## Permissions
8+
9+
The application must have at least edit permissions to the SharePoint list where the subscription will be updated.
10+
11+
**If your application is an Microsoft Azure Active Directory (AD) application:**
12+
13+
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.
14+
15+
Application | Permission
16+
------------|------------
17+
Office 365 SharePoint Online|Read and write items and lists in all site collections.
18+
19+
**If your application is a SharePoint add-in:**
20+
21+
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.
22+
23+
Scope | Permission Rights
24+
------|------------
25+
List|Manage
26+
27+
## HTTP request
28+
29+
```
30+
PATCH _api/web/lists('list-id')/subscriptions('id')
31+
```
32+
33+
### Example
34+
35+
```http
36+
PATCH _api/web/lists('5C77031A-9621-4DFC-BB5D-57803A94E91D')/subscriptions('6D77031A-2345-5GRT-BV3D-55234B56FR43')
37+
Content-Type: application/json
38+
39+
{
40+
"notificationUrl": "https://contoso.azurewebsites.net/api/v2/webhook-receiver",
41+
"expirationDateTime": "2016-01-03T11:23:00.000Z"
42+
}
43+
```
44+
45+
## Request body
46+
47+
Include the following properties in the request body.
48+
49+
Name | Type | Description
50+
-----|------|------------
51+
notificationUrl|string|The service URL to send notifications to.
52+
expirationDateTime|date|The date the notification will expire and be deleted.
53+
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.
54+
55+
56+
## Response
57+
58+
If the subscription is found and successfully updated, then a `204 No Content` response is returned:
59+
60+
### Example
61+
62+
```http
63+
HTTP/1.1 204 No Content
64+
```

0 commit comments

Comments
 (0)