How to debug SharePoint Webhooks locally ?

Early this year there was a announcement for General Availability (GA) of SharePoint Wehbooks meaning that developers can leverage webhooks in their production SharePoint sites. There has been quite some development around webhooks to get a developer started with it in different flavors like Node.js , Azure AD app, Azure Functions etc. These samples can be found on github with sufficient documentation to get you started.

This post would focus on how you can locally debug your SharePoint webhooks application. 
To give a bit of overview , SharePoint webhooks allows you to build applications that receive notifications from specific events that occur in SharePoint. For eg, SharePoint webhooks can notify your application when there is change/update in list item. 
If you are new to webhooks I recommend going through the links at the end of the post and setup a play ground as per the lucid documentation here.

As everything is hosted on azure it becomes hard to debug through the development stage. Moreover the remote debugging from Visual Studio is extremely slow which just makes it impossible to debug.

I assume you have all the components ready in Azure and SharePoint as described here. We will debug this project so its good to have it set up before hand.

1. Create a site in IIS and assign it a certificate.

a) Open Run and type inetmgr. This should open the your IIS manger on your system. Right click sites and click ‘Add website’.

b) Fill in the details as below and click OK

Fig 1

c) Now run Notepad as administrator and open the hosts file from this location ‘ C:\Windows\System32\Drivers\etc\’.

d) Add an entry SPWebhooksDemo and save the file.

e) Create a self signed certificate using powershell. You can also use makecert for creating a certificate if you dont have powershell installed.

f) Run powershell terminal as administrator and run the below command,

New-SelfSignedCertificate -DnsName SPWebhooksDemo -CertStoreLocation cert:\LocalMachine\My

You need not replace the \LocalMachine\My path.

The output is as below,

Fig 2

g) Now go to IIS manager > Server Certificates

Fig 3

h) Double click on the newly created certificate and then Copy to file..

i) Click next and follow the options in below screenshots.

j) Click Browse and give a name to certificate and click save. Remember the location where you save the certificate.

k) Click Next and then Finish. Your certificate has been successfully exported

l ) Now go to the location where you saved the certificate from last step and click Install certificate.

m) Follow the below screens,

n) Now go to your IIS site and enable Directory browsing

o) Right click the site we created and click Edit Bindings. Click on Add and match the details as below screen. Your certificate will appear in the SSL certificate dropdown. And click OK

p) Now you should be able to browse the site, https://SPWebHooksDemo with no errors

2. Register an new provider hosted add-in in SharePoint.

Prerequisite: App catalog in SharePoint

a) Go to <you-sharepoint-site>/_layouts/appregnew.aspx to register an new provider hosted add-in. Click on Generate button against Client ID and Client Secret. Give a title to your app. And the app domain should match the hostname for your IIS site, in our case SPWebhooksDemo. And click Create.

b) Store the Client ID and Client Secret somewhere, we will need this .

3. Update our project

a) Open the SharePoint.WebHooks.sln under the Webhooks.List folder. (Hope you have downloaded the project and set it up as per this guide.)

b) Open the app.config under SharePoint.Webhooks.Job project and update the ClientId and ClientSecret you generated from STEP 2.

c) Now update the same ClientId and ClientSecret for Web.config under SharePoint.Webhooks.MVCWeb project.

d) Update the ClientId in AppManifest.xml under SharePoint.Webhooks.MVC project which is our provider hosted add-in

4. Publish our App

a) Right click SharePoint.Webhooks.MVCWeb project and click Properties, and match the below screen. And click Create Virtual Directory.

b)To verify go to IIS and expand your site. It should have folder created as below.

c) Right click the SharePoint.WebHooks.MVCWeb project and select Publish.

Click on Custom and give it a name

d) On the below screen do not fill anything and click Close

e) Click Yes to save the changes

f) Now right click SharePoint.Webhooks.MVC project and click Publish.

g) Click on edit and fill in the ClientId and Client Secret from STEP 2. Click Finish

h) Now click Package the app and enter the url IIS site. And click Finish. It will now create and .app file

5. Deploy the app.

a) Inside your project under bin> Debug > app.publish > you will find the that was created from previous step.

b) Upload this .app to your app catalog at

c) Go to the site collection where you wish to deploy this app and add the app.

d) Click on trust it

e) It might take a few mins for your app to be available in the site contents page.

f ) Click on the app from the site contents page and if everthing was OK then you should see this screen,

6. Debug the provider hosted add-in locally

a) This is what we have waited for and I know it has been a long journey if you are reading this. So get ready to debug the shit out of it. :)

b) Go to your visual studio > Debug > Attach to Process

c) Select the w3wp process and click attach.

d) Set a breakpoint at the start of Home controller

e) NOW REFRESH the page. You must see it hitting the break point.

f) Rejoice now you shall be able to debug your provider hosted add-in. But most of the time this is not what you want to debug. You will need to debug the code when a event is triggered on a SharePoint list. This code is in the ChangeManger.cs and it is invoked by the Webjob whenever there is new entry in Azure storage queue. I wont go in details how the webhook are trigerred but will place some links where you can understand the complete picture of the solution. Keep Reading..

7. Debugging the end point that SharePoint notifies in case of any event in a list.

a) At this moment if you wish to create a webhook on a SP list then the endpoint SP will notify for any change in list is actually the one hosted on azure. Check your web.config under appSettings.

It will be the url for your web app that you created. This is perfect for production but while development stages you will need this endpoint locally so that you can debug.

The problem is you cannot ask SharePoint to notify a localhost or any website from your IIS running locally.

b) There is one way to achieve this using ngrok. It creates a secure tunnel to your localhost giving you an public domain. Go and download it.

c) Go to the folder you have downloaded it and run the ngrok.exe. This will open a command prompt and type below command,

ngrok http 80 -host-header=”SPWebhooksDemo:80"

and hit enter.

d) It will output the public address that tunnel to your website

e) Copy the address with https and replace the WebHookEndPoint in web.config with this address.

f) Also do the same for the app.config in SharePoint.WebhooksJob project

g) Build your solution.

h) Now go the app and add a webhook an a list. After successful creation you should see a list like,

This shows that now your list will notify the endpoint that ngrok has generated for us.

i) Now run the SharePoint.Webhooks.Job project from Visual studio and place a break point somewhere at the start of ProcessNotification method in ChangeManager.cs

j) Go to the list for which webhook is created and add a item in it. Your code should hit the above break point. It may not immediately hit because the notification first needs to storage queue and your webjob will process it as it arrives.

You have reached your destination :)

Note: As we are using the free tier of ngrok, everytime the ngrok.exe is stopped and run again a new address will be provided. You will then again have to update the web.config and app.config as well as reattach the webhook to list from the add-in so that SharePoint will notify the new address.

1. Overview of SP Webhooks

2. How webhooks work ?

3. Sample implementation for webhooks