Tech Blog

Debugging Webhooks

Webhooks were introduced several years ago and are a great way to have Alma notify you when events happen the system. We continue to see increased webhook usage – last month Alma sent almost 20 million webhook requests!

In previous blog posts, we’ve seen how to develop a webhook listener locally. In this post, we’ll use a similar methodology to show how we can receive webhook requests from Alma and debug a listener locally.

We’ll be using the Node debugging capabilities of Visual Studio Code. A good primer is available in the VS Code documentation. And we’ll use the simple Node.js server shown in this gist. To set up, create a new directory on a machine which has Node.js installed, and save the code in the gist as a file called index.js in the new directory. Then install the dependencies as follows:

$ npm install body-parser express

To debug the file, click the debug tab in VS Code, then click the Start Debug button. The debug console will show that the app is running on port 8000. Go to http://localhost:8000 in your browser and make sure you see “Hello from Express!”.

Of course, we can’t use the local address when configuring Alma, so we need to use an Internet proxy. We’re using the ngrok service* which provides a public URL and proxies requests to your local program. After installing ngrok, we start the proxy from the command line:

$ ngrok http 8000

ngrok by @inconshreveable                                                                                                                                                                    (Ctrl+C to quit)
                                                                                                                                                                                                             
Session Status                online                                                                                                                                                                         
Account                       *** (Plan: Free)                                                                                                                                                      
Version                       2.3.35                                                                                                                                                                         
Region                        United States (us)                                                                                                                                                             
Web Interface                 http://127.0.0.1:4040                                                                                                                                                          
Forwarding                    http://4d380***.ngrok.io -> http://localhost:8000                                                                                                                          
Forwarding                    https://4d380***.ngrok.io -> http://localhost:8000

We can now follow the instructions to configure Alma to send webhooks to the address ngrok provides. If we add a breakpoint in the POST function, when Alma sends a webhook request we will receive the request on our local server and the debugger will hit the breakpoint. There we can use all of the standard debugging features such as stack trace, watch variables, etc.

The video below shows the process in action. Hope this helps in your webhook listener development.

* Thanks to Liam Toohey for introducing me to ngrok in his ELUNA Learns presentation.

Leave a Reply