This document discusses webhooks in SharePoint and how to use them. It defines webhooks as asynchronous event notifications triggered by actions on a web service. The document outlines how to subscribe to webhook notifications in SharePoint lists and libraries, how the minimal notification information can be used to retrieve change details from SharePoint, and provides examples of creating a notification service using technologies like Node.js and Azure Functions.

1. Elio Struyf
Trainer @ U2U – MVP
October 25th, 2017
Getting notified by SharePoint with
WebHooks

3. #SPUnite17 - @eliostruyf
What are WebHooks?

4. #SPUnite17 - @eliostruyf
What are WebHooks?
• Event driven notifications AKA callbacks from the web
• Universal model used by many services: GitHub, Slack, MailChimp, …
• Pushing mechanism à asynchronous!
• Implemented in various Office 365 Services
• Microsoft Graph
• Connectors
• SharePoint

5. #SPUnite17 - @eliostruyf
WebHooks in SPO went GA
in January 2017

6. #SPUnite17 - @eliostruyf
Where can you use them?
• SharePoint
• List
• Libraries
• Microsoft Graph
• Messages, events, contacts, conversations in groups, OneDrive root items

7. #SPUnite17 - @eliostruyf
The good and the bad
• WebHooks are asynchronous mechanism
• Retry mechanism
• 5 times with a delay of 5 minutes
• More secure, no event information is passed
• No support for event-ing events à only RER can be used
• Add-ing, update-ing, delete-ing
• Requires some setup, but once done, it is easy to maintain

8. #SPUnite17 - @eliostruyf
Remote event receivers vs WebHooks
Remote event receivers
• Synchronous (-ing) and/or async (-ed)
• One request
• One change = one request
• Changes are inside the request body
• 2 minutes to respond
• Indefinitely
• One try
WebHooks
• Async only
• Retry logic: 5 times
• Batched requests
• Only notification à more secure
• 5 seconds to respond
• Needs subscription renewal
• When it fails, you can try again later
Both use the same base principle: call an external URI when something happens

9. #SPUnite17 - @eliostruyf
How to start using
WebHooks?

10. #SPUnite17 - @eliostruyf
By subscribing to a WebHook!
Notification service
1. Create a subscription
4. SharePoint responds with subscription info

11. #SPUnite17 - @eliostruyf
Important things about subscribing
Subscribing: POST - /_api/web/lists/getbytitle('Title')/subscriptions
{
"resource": "https://tenant.sharepoint.com/sites/site/_api/web/lists/getbytitle('Title')",
"notificationUrl": "Your notification service URL – HTTPS is required",
"expirationDateTime": "Date value - maximum 6 months",
"clientState": "String value for validation (optional)"
}

12. #SPUnite17 - @eliostruyf
Important things about subscribing
SharePoint calls your notification service:
POST - https://notification-service?validationToken={random-guid}
Respond with:
Important: notification service needs to respond in < 5 seconds
Status: 200
Body: validationtoken

13. #SPUnite17 - @eliostruyf
Important things about subscribing
When validation is done, SharePoint returns the subscription
information

14. #SPUnite17 - @eliostruyf
Local development and testing:
ngrok - Secure tunnels to localhost
https://ngrok.com/

16. #SPUnite17 - @eliostruyf
Demo
Subscribing to a WebHook

17. #SPUnite17 - @eliostruyf
More about the notification
service

18. #SPUnite17 - @eliostruyf
Notification service details
• You choose the technology: Web API, Node.js, …
• Respond in < 5 seconds and with status: 200-299 range
• Retry mechanism à 5 times (5 minute in between)
• Not for the validation process
• Receives minimal information, just a message “something” happened
• Service has to gather the changes from SharePoint

19. #SPUnite17 - @eliostruyf
Minimal notification information?

20. #SPUnite17 - @eliostruyf
This is what you will receive
{
"value": [
{
"subscriptionId":"2e7f9cd7-5cdb-4d57-b4d5-edc083202378",
"clientState":null,
"expirationDateTime":"2017-08-16T10:38:54.3440000Z",
"resource":"465b36fc-e778-4047-8425-3f906497dfc3",
"tenantId":"9fee8694-d491-4e3e-b10b-a81ee76dfad9",
"siteUrl":"/sites/Webhooks",
"webId":"e363e4e9-0161-495f-a652-15c618e2e963“
}]
}

21. #SPUnite17 - @eliostruyf
How do I know what happened?
• SPList.GetChanges method
• POST - `/_api/web/lists(guid'${resource}')/getchanges`
• Specify a change query + change token
{
"Item": true,
"Add": true,
"Update": true,
"DeleteObject": true,
"Restore": true,
"ChangeTokenStart": {
"StringValue": "1;3;465b36fc-e778-4047-8425-3f906497dfc3;636307008298500000;60877869"
}
}
ChangeQuery properties: http://elst.es/2rib2q7

22. #SPUnite17 - @eliostruyf
Anatomy of the change token
1;3;465b36fc-e778-4047-8425-3f906497dfc3;636307008298500000;60877869
Version information (currently always 1)
Scope of the change. 3 = List & library changes.
Resource ID, can be retrieved from the subscription notification
Timestamp in ticks
Change number
in the event
cache table. You
can start with -1.

23. #SPUnite17 - @eliostruyf
Using the change token
• Using GetChanges without ChangeToken would return everything
• By specifying a change token, you control what you need

24. #SPUnite17 - @eliostruyf
Things to know about the change token
• First time, create it yourself (ex.: get all changes of the last hour)
• Per GetChanges request, you get the latest change token
• Store the latest change token, use it for the next call
{
"ChangeToken": {
"StringValue":"1;3;465b36fc-e778-4047-8425-3f906497dfc3;636307074435230000;60879219"
},
"ChangeType": 2,
"SiteId": "1432d309-9f6a-4dae-8d35-532dec332b86",
"ItemId": 3,
…
}

25. #SPUnite17 - @eliostruyf
GetChanges response value
• Notice the ChangeType, it is an enumeration
• 1 = added, 2 = updated, 3 = deleted
{
"ChangeToken": {
"StringValue":"1;3;465b36fc-e778-4047-8425-3f906497dfc3;636307074435230000;60879219"
},
"ChangeType": 2,
"SiteId": "1432d309-9f6a-4dae-8d35-532dec332b86",
"ItemId": 3,
"ServerRelativeUrl":"",
…
"WebId":"e363e4e9-0161-495f-a652-15c618e2e963"
}
More information about the ChangeTypes - http://elst.es/2ruAfKn

26. #SPUnite17 - @eliostruyf
Supported event types
• Added
• Updated
• Deleted
• CheckedOut
• CheckedIn
• UncheckedOut
• AttachmentAdded
• AttachmentDeleted
• FileMoved
• VersionDeleted
• FileConverted

27. #SPUnite17 - @eliostruyf
Creating your notification
service

30. #SPUnite17 - @eliostruyf
Tokens, all about the OAuth tokens
• Azure AD app registration
• Generate a certificate
• SharePoint requires access tokens with appidacr property set to 2
• Application Authentication Context Class Reference
• 0 = Public client
• 1 = Identified by a client id and secret
• 2 = Identified by a certificate

31. Azure AD application manifest
Store this in a separate file (privatekey.pem)
Fingerprint is also require to get the access token

33. #SPUnite17 - @eliostruyf
public getAppOnlyAccessToken(config: IConfig): Promise<any> {
return new Promise((resolve, reject) => {
const certificate = fs.readFileSync(path.join(__dirname, 'privatekey.pem'), { encoding :
'utf8'});
const authContext = new adal.AuthenticationContext(config.adalConfig.authority);
authContext.acquireTokenWithClientCertificate(config.adalConfig.resource,
config.adalConfig.clientID, certificate, config.adalConfig.fingerPrint, (err, tokenRes) => {
if (err) {
reject(err);
}
const accesstoken = tokenRes.accessToken;
resolve(accesstoken);
});
});
}
Get an access token via a certificate and
private key with ADAL for JS

34. #SPUnite17 - @eliostruyf
Important APIs
• Retrieve all list / library subscriptions
GET - /_api/web/lists/getbytitle('ListTitle')/subscriptions
• Update a subscription
PATCH - /_api/web/lists/getbytitle('ListTitle')/subscriptions('${subId}')
Body: { "expirationDateTime": "New expiration date" }
• Delete a subscription
DELETE - /_api/web/lists/getbytitle('ListTitle')/subscriptions('${subId}')

35. #SPUnite17 - @eliostruyf
Demo
Sample application

36. #SPUnite17 - @eliostruyf
A real life setup and configuration
SPO config page
HTTP Triggered function
Queue triggered function
1. Subscribe 2. Validate
3. Trigger change
4. Notify service
5. Put notification message on a queue6. Respond with 200
Use the page to:
- Check subscriptions
- Update subscriptions
- Delete subscriptions
7. Trigger another Azure function that will do change handling
8. Retrieve latest change token10. Store latest change token

37. #SPUnite17 - @eliostruyf
Demo
SPFx + Azure Functions

38. #SPUnite17 - @eliostruyf
Recap
• Notification service has to respond in < 5 seconds
• Retry mechanism à 5 times (5 minute delay)
• Not for the validation process
• Subscription expiration date: 6 months
• Create a check or renewal process in your subscription processor
• You need to ask for the changes that happened à minimal
information is send
• Get the changes only what you are interested in
• No synchronous events for SPO à event-ing events

39. Questions?

40. Office Servers & Services MVP
Azure / Office 365 / SharePoint
@eliostruyf
www.eliostruyf.com
info@estruyf.be
Elio Struyf
Lead trainer and architect

41. #SPUnite17 - @eliostruyf
Resources
Certificate creation process with makecert - http://elst.es/2rhveZc
Keycred GitHub - http://elst.es/2pW77vm
All about the Change token - http://elst.es/2runG1M
ChangeType enumeration - http://elst.es/2ruAfKn
ChangeQuery properties - http://elst.es/2rib2q7
C# Sample application - http://elst.es/2qUYg0M
Node.js / TypeScript sample application - http://elst.es/2qVpTqT or http://elst.es/2cycM82
SharePoint List WebHooks docs - http://elst.es/2qwl1as - http://elst.es/2quVjD0

42. #SPUnite17 - @eliostruyf