We Are Hiring

Test SendGrid Webhooks with ngrok


Posted on

ngrok-logo

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:

Running the NodeJS app

 

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:

Run ngrok on port 3000

 

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

ngrok up and running

 

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:

Event Notification Settings

 

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!

Successful test

 

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

200 OK

 

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:

ngrok web interface

 

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.

Tags: , ,


Martyn Davies is a Developer Evangelist at SendGrid and a creative developer based in London. He has worked in technology for over 14 years with a background in both the music industry and technology. A serial hackathon organiser, mentor and startup advisor, you’ll find him presenting, demoing, hacking and chatting at hack days, conferences and meetups in the UK & Europe on a regular basis.

4 thoughts on “Test SendGrid Webhooks with ngrok

  1. Pingback: Collect Inbound Email Using Python and Flask

  2. Pingback: Receive Inbound Email with MeteorJS

  3. Pingback: Control Home Lighting with the Parse Webhook

  4. Pingback: How to Get SMS Alerts When a User Opens an Email

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>