How To Use Visual Studio Dev Tunnels to Receive Webhooks on Localhost

TL;DR: In this blog post, I'll show you how you can use Visual Studio Dev Tunnels to receive webhooks on your localhost. There are many alternative third-party proxy tools out there; this is just one of them.

One of my many frustrations when working with webhooks is the process to debug applications on my localhost. I've considered several alternatives: third-party proxies, tunnels, hosting it on a cloud service and attaching my debugger to it. My workflow looks something like this:

1. Download a third-party tool.
2. Make my localhost publicly available through this third-party tool.
3. Update/configure the webhook URL.
4. Repeat the previous step when my laptop goes into standby mode or the tunnel breaks.

A quick note: some companies don't allow you to set up a third-party proxy, especially when you're connected to their intranet!

In an ideal world, I'd like to press the Run-button and start debugging my application right away where everything is already set up. Configure once. Run and debug for as long as I am working on the application. This is where I came across Visual Studio dev tunnels (formerly known as port tunneling).

Visual Studio Dev Tunnels

To receive webhooks, it boils down to two main things:

1. Make my endpoints publicly available through a proxy.
2. Configure/update the webhook URL so that my endpoint can receive events through this proxy.

With the release of Visual Studio 17.4 or higher, they have introduced a new feature "Visual Studio Dev Tunnels" that allows you to create a proxy to your local machine. It also keeps the tunnel up and running until you close it. It has significantly improved my developer experience and sped up my workflow.

Update: As of Visual Studio 17.6+, you can now create a (public/private) persistent or temporary tunnel within the Visual Studio wizard. You will no longer need the extra configuration in your project.

For earlier versions, we'll use an ASP.NET Core project in Visual Studio and set up a tunnel. The following guide can be applied to any webhook. For your convenience, a fully working integration example can be found in the .NET Adyen examples repository. Let's take a look at the steps needed to configure your tunnel.

1. Sign in to Visual Studio.
2. Under Options → Environment → Preview Features → Check Enable dev tunnels for Web Application.

Enable dev tunnels for Web Applications in the Visual Studio Preview Features screen.3. In your launchSettings.json, add the following two properties:

devTunnelsEnabled: <Boolean> [true, false]
devTunnelAccess: <String> [ "public", "private", "org"]
//public: Anyone can access this tunnel.
//private: Only the logged-in user can access this tunnel.
//org: Only users within the same organization as the logged-in user can access this tunnel.

See an example of a launchSetting.json profile below.

{
  "DevTunnelsProfile": {
    "commandName": "Project",
    "launchBrowser": true,
    "environmentVariables": {
      "ASPNETCORE_ENVIRONMENT": "Development"
    },
    "applicationUrl": "https://localhost:5001;http://localhost:8080",
    "devTunnelEnabled": true,
    "devTunnelAccess": "public"
}

The next step is to configure your webhook. You usually configure this in some kind of portal that is provided by the organization you're trying to receive webhooks from. Your webhook URL should point to this temporary auto-generated URL that is created when you start the application (e.g. https://*.euw.devtunnels.ms). As long as you do not close Visual Studio, this URL will remain the same. In future updates, we will be able to create a durable URL which persists even after you restart or close Visual Studio.

Retrieving the URL dynamically

Visual Studio exposes this URL as an environmental variable VS_TUNNEL_URL at run-time. This allows developers to programmatically update the webhook URL if needed. For multiple projects, the environmental variable looks like VS_TUNNEL_URL_PROJECTNAME where PROJECTNAME is the name of your project.

For an ASP.NET project, you retrieve it like this:

// From Microsoft.Extensions.Configuration.IConfiguration 
Configuration["VS_TUNNEL_URL"];
Configuration["VS_TUNNEL_URL_PROJECTNAME"];

// From System.Environment.GetEnvironmentVariable(...)
Environment.GetEnvironmentVariable("VS_TUNNEL_URL");
Environment.GetEnvironmentVariable("VS_TUNNEL_URL_PROJECTNAME");

All that's left is starting your application. Once started, you'll see the created tunnel and the auto-generated URL in the output window.

That's it. Happy debugging!