Test SendGrid Webhooks with ngrok

SendGrid’s webhooks for inbound parse (receiving email) and events are great for hacking with, but they can be difficult to test in a productive manner because you have to keep deploying your code to the live server in order to get our webhooks to hit it, right?

Wrong. In this post I’m going to show you how to work with ngrok to make local development with webhooks easier than ever.

Install ngrok on Your Development Machine

It’s always nice when there’s a good set of installers for things like this, you can download ngrok for OSX, Linux and Windows.

It’s worth noting that ngrok doesn’t automatically symlink to your /bin folder, so to start out just copy the ngrok file directly into the project you want to use it with (add ngrok to your .gitignore too).

Run ngrok

Open a new terminal tab/window and navigate to your project. I’m using a NodeJS application, it runs on port 3000.

Let’s start by running that application:

 

Great, the app is running and if I head to http://localhost:3000 in my browser I can play with it, but it’s still not accessible from the outside world.

Let’s use ngrok to make that possible. Open up another terminal tab/window, separate from the one your app is running in.

We need to open up port 3000 to the world, we can do that by adding the port number we want to use as an argument when we run ngrok, like so:

 

When you hit enter you’ll see something like this:

 

Now port 3000 is available to the outside world at http://e0e616c.ngrok.com (your URL will be different). If you grab and head to that URL in your browser you’ll see your app. Awesome!

Implement SendGrid

Let’s get some events from our SendGrid account flowing through to the app. As we’re just debugging this setup I’ve created an endpoint inside my app that just spits out what it receives to the console.

To the outside world, this endpoint will accept a POST request on http://e0e616c.ngrok.com/inbound. This is the URL that we need to put in SendGrid’s Event Notification app so we can receive our notifications.

Login to SendGrid, then click Apps > Event Notification > Settings and add your ngrok URL plus your endpoint (http://e0e616c.ngrok.com/inbound) into the text box marked HTTP Post URL:

 

Handily, you can check if this is working straight away by hitting the blue ‘Test Your Integration’ button, it’ll pop up a dialogue that will send a bunch of test data through to your app. If all is well then you’ll get you some green!

 

200 OK! That’s what we like to see. Additionally, you’ll see the request come into ngrok in your terminal

 

You are up and running. Test away friends, send some emails from your SendGrid account and watch the resulting event notifications flow back into the app running on your laptop, in real time.

Note: When you actually deploy your app to a server, don’t forget to change the HTTP Post URL inside SendGrid. It’s easy to forget.

But that’s not all!

Oh no, there’s one more aspect of ngrok that is super useful. The web interface.

When you run ngrok, you get another URL listed: http://127.0.0.1:4040 – this is how you access the ngrok web interface and some additional useful features, the most important of which is on the right hand side of the page:

 

You can click through each request that came in to ngrok and use this inspector to check every detail, which is much cleaner than trying to scroll back through many rows of console.log output to find what you need, you get a ton of detail.

By far the most useful, especially if you’re using the inbound parse webhook with ngrok, is the Replay button. This allows you to replay any request that has been made to your app via ngrok. So, rather than wait for another email to parse, or an event to fire, just keep clicking the replay button and use what it gives you to continue building out your app.

Dig deeper

I’ve covered the basics and the aspects of ngrok I feel are most important. Based on usage at hackathons this is about as far as I need to take it, but there are loads more excellent features to ngrok that I suggest you check out, such as custom subdomains, multiple instances and customisable config files.

All that and more can be found in the ngrok documentation, go and experiment.

You can also check the Debugging Webhooks section of our documentation for more information and tools that can help you out when work working with SendGrid’s webhooks.