I use Ngrok as a tool to expose my local server to the internet. It helps me by creating a secure tunnel from the public internet to my application on my local machine without changing anything in your network's firewall.

This is extremely useful when I need to test an external web service that is pushing data to our applications. Especially when there is an error with that service in production, or when I can't use it directly for local development. Sometimes the error only occurs in your web application in production mode. Then, it could be a data error where your local environments can't access this data directly.

And now in Umbraco 13, you have webhooks. Here, you can also benefit from the use of Ngrok. So you build an application that can receive the data from your website. And the webhook is working in the test environment. But as soon as you deploy it in production, the webhook is not working, and an error occurs in your custom application.

Then you can get the data and try it locally, but you also can set up a webhook to the Ngrok URL to test it directly. This way, you can use your production website with your local application to see what is happening.

I will show you how to set up this in the following steps.

First, I set up a .NET project for receiving the webhook. I'm using an empty ASP.NET Web Core API template.

Here, I placed the following basic models for receiving the request from the webhook.

public class PublishedContentRequest
{
    public string Name { get; set; }
    public DateTime CreateDate { get; set; }
    public DateTime UpdateDate { get; set; }
    public RouteItem Route { get; set; }
    public string Id { get; set; }
    public string ContentType { get; set; }
    public object Properties { get; set; }
}

public class RouteItem
{
    public string Path { get; set; }
    public StartItem StartItem { get; set; }
}

public class StartItem
{
    public string Id { get; set; }
    public string Path { get; set; }
}

I generated this with the usage of the receiving Json and converted this online using https://app.quicktype.io/

Next, we are gonna create a basic controller for receiving the publish request.

[ApiController]
[Route("[controller]")]
public class PublishedContentController : ControllerBase
{
    [HttpPost]
    public IActionResult Post([FromBody] PublishedContentRequest publishedContentRequest)
    {
        // Handle the publishedContentRequest here
        // For example, save to a database or perform other operations
        var name = publishedContentRequest.Name;
        return Ok("Thanks");
    }
}

The controller is more of an example of receiving. It is currently not doing anything but we want to keep the logic as simple as possible. 

 

Now if we run this application it is ready to receive the data from a webhook or api call. Now in the following steps I'm going to describe how to setup Ngrok in a couple of easy steps.

First, download Ngrok from here: https://ngrok.com/download

you need to authenticate it using the login where you are gonna get a token. The call for registering the token is done with the following command.

ngrok config add-authtoken <token>

here you need to replace the <token> with the token you get from login / registering online in Ngrok portal.

Next up you need to startup and bind your local development environment with the Ngrok.

First, run the .NET Application. 

Mine is running on https://localhost:7178/ so we need to register this for Ngrok using the following command

 

.\ngrok.exe http https://localhost:7178/

If you have set the authentication token Ngrok will startup. You will see a similar screen like this:

 

Ngrok Shell

Now we are ready to configure our Umbraco Webhook.

in Umbraco 13 navigate to settings and select webhooks.

We create a new webhook with the URL of our Ngrok environment and the endpoint of our application.

This is in my case:

https://6f51-178-84-167-157.ngrok-free.app/publishedcontent

Then we select the event type and content type. I'm only using it for my Blog articles.

And now save it.

Webhook Umbraco13

Now we can publish a blog item on this site and the webhook will be activated on my local machine from my online website environment.

If you have issues first check the Umbraco webhook deliveries log. Next up you can see it in the local web environment of Ngrok.

See the previous screenshot of the command line. You can find the URL for the user interface of Ngrok from the console output where the web interface is mentioned.

In the interface, you can see the call I made from a previous blog item. And you also see an option for replay and information about the requests. Handy to replay the call without executing the call from the website again and again.

Ngrok Portal

So now I'm getting the request in my .NET application and can do stuff with it. Umbraco has good documentation about their webhooks. You can read them here. https://docs.umbraco.com/umbraco-cms/reference/webhooks

 

Short recap

With this article, I hope to provide a simple guide for developers on using Ngrok to debug webhooks, specifically in a .NET project environment. It includes steps for setting up the project to handle webhook data, creating models, and a controller for processing webhook requests. With basic configuring of Ngrok for authentication and binding it to a local development environment you can test and debug your local environments with online webhooks / APIs.

If you need any help or have a question contact me using any of my social networks