Home » Extensibility » Wizdom webhooks
PRINT

Wizdom webhooks

Webhooks allow you subscribe to certain events in Wizdom. When one of those events is triggered, Wizdom will send a HTTP POST payload to the webhooks configured URL.

Typical use cases

  • Modify a site after it has been created
  • Push notification to users when a noticeboard item has been created
  • React on changes to project roles and metadata

Authentication

Wizdom Webhooks are not authenticated so be aware a webhook URL defined in the Wizdom Configuration Center can access the SharePoint resource on behalf of the user/app. The configured URL will receive the following header to be able to impersonate current user/app.

  • “WizdomSPToken”, “[SharePoint access token]”

If webhooks need to call back to the Wizdom API it needs to be authenticated. To call back to SharePoint using CSOM, the WizdomSPToken can be used. The Wizdom API uses OAuth 2.0 to handle authentication and authorization. Before using the Wizdom API an Azure Active Directory application with correct permission scope needs to be created. This app will provide the authentication service for accessing the Wizdom API.

Visual Studio 2017 / .NET web application sample

This section will provide a sample on how to use the Wizdom Webhooks. In about ten minutes you’ll have a simple .NET web application that receives a HTTP POST payload from Wizdom. The application is then able to read information from the newly created site. The application is also able to makes requests to the Wizdom API and retrieve comment details from the Wizdom Noticeboard service.

The sample uses WizdomSPToken to execute queries against SharePoint. It uses resource owner password credentials grant type, where the user provides their service credentials (username and password) to access the Wizdom services. This type uses the credentials to obtain an access token from the service. This grant type should only be enabled on the authorization server if other flows are not viable. Also, it should only be used if the application is trusted by the user (e.g. it is owned by the service, or the user’s desktop OS).

Prerequisites:

  • Visual Studio 2017
  • Office 365 site collection with Wizdom installed

Step 1: Create a .NET web application

1. Create ASP.NET (Web Application) and choose WebAPI, no authentication

2. Use a tool like ngrok to setup a tunnel to localhost. https://ngrok.com/
This is needed for the azurewebsite to reach your local dev environment.
ex. ./ngrok.exe http 51191 -host-header=”localhost:51191″

Step 2: Setup the Azure Active Directory Application

1. Navigate to the Azure Portal (https://aad.portal.azure.com) logged in as your tenant admin.

2. Navigate to Azure Active Directory > App Registrations

3. Add app (new application registration).

4. Give it a name and choose Application Type: Web app / API

5. Enter the url of your previously created ngrok url
ex. https://98697d65.ngrok.io

6. Assign required permissions (delegated and application)
Azure AD: Read Directory data
SharePoint: Read Items in all site collections + Read user profiles
Yammer: Read and Write

7. Create Key and save/copy it.

8. Press the “Grant Permissions” button.

Step 3: Setup the sample

Add app settings to the web.config. Replace the values in brackets.

2. Add a new model called: SiteItem
3. Add a new model called: CommentItem
4. Add an empty Web API 2 controller to the project. Name it WebhookController

5. Install nuget package: Install-Package Microsoft.SharePointOnline.CSOM -Version 16.1.6906.1200

6. Replace the class with this code and resolve the missing references.

7. Navigate to the Wizdom Configuration Center > Admin > Webhooks and add the following webhooks
CommentUpdated : https://266830b2.ngrok.io/api/webhook/commentupdated
WizdomSiteCreated : https://266830b2.ngrok.io/api/webhook/webcreated

8. Start your application and set a breakpoint in each Method.

9. Create a noticeboard news item. Create a comment and edit that comment. Verify you breakpoint is hit.

10. Create a new Wizdom site. Verify that your breakpoint is hit.
This concludes this sample application.