Receiving SMS with a webhook with Nexmo and Node.js

How to Receive SMS Messages with Node.js and Express

Published October 27, 2016 by Tomomi Imura

This is the second article in a series of “Getting Started with Nexmo and Node.js” tutorials.

In the previous article, you set up your Nexmo account and learned how to send SMS messages with Node.js. In this article, you will learn about receiving an inbound SMS by implementing a webhook endpoint in Node.js using Express.

GitHub icon View the source code on GitHub

Defining a Webhook Endpoint

In order to receive an SMS from Nexmo you need to associate a webhook endpoint (URL) with a virtual number that you have rented from Nexmo. Inbound Messages to that number are then sent to your webhook endpoint.

A diagram showing how a SMS is received from a user

While you are developing the webhook endpoint, it is a pain to keep deploying your work in progress. To make your life easier, let’s use ngrok to expose your webhook endpoint on your local machine as a public URL!

Using ngrok

First, download ngrok from Once installed, run ngrok on terminal:

running ngrok

Your local server (localhost:3000) now has a ngrok URL, that can be used as your webhook endpoint during development (also, notice the Web Interface URL – I will explain it later!).

Setting the Webhook Endpoint with Nexmo

Sign in to your Nexmo account, and go to Settings. Scroll all way down to API Settings and fill out the Callback URL for Inbound Message with the ngrok URL with a route, let’s call it inbound, enter, and let’s set the HTTP Method to POST then save.

setting your webhook endpoint

Now all your incoming messages will go to the webhook (callback) URL, so let’s write some code with Node.js and Express!

Note: Above we’re setting the webhook endpoint for SMS at an account level. But you can also set up unique webhook endpoints for each virtual number.

Writing WebHook Endpoints with Express

Now, handle the POST requests with Express, so you will also need to install body-parser.

Create a .js file, and instantiate express and listen the server to port 3000. Because you have set your ngrok to expose localhost:3000, you must stick with the same port.

Now, create a HTTP POST route to handle the requests:

Then define the handleParams function:

Let’s run the node code, and try sending some messages from your phone to your virtual number!

screenshot of a user sending a sms message from an Android phone

When you are tunneling your local app with ngrok, you can also inspect the request at on your browser:

ngrok inspector

Voilà, now you can see your SMS message has been sent, Nexmo has received the message and passed it on to your express application via a webhook!

If you take a look at the code sample in GitHub, you will notice the extra example – a persist data storage (like the HTML5 Local Storage, but for Node) and the incoming data is stored with each key (message ID) and values. That way, you can set up a /inbound/:id route parameter as named URL segment. For instance, when you access http://localhost:3000/inbound/080000001947F7B2, it returns:

In reality, you should set up a real DB, rather than the data storage.

I hope you find this useful. Let me know, I’m @girlie_mac on Twitter.


Nexmo Logo

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at