Webhooks

Webhooks are an extension of an API, but instead of your code requesting data from Nexmo, Nexmo sends data to you. The data arrives in a web request to your application. A webhook may be the result of an earlier API call (this type of webhook is also called a "callback"), such as an asynchronous request to the Number Insight API. Webhooks are also used to notify your application of events such as an incoming call or message.

Since the Nexmo servers need to be able to send data to your application via webhooks, you need to set up a webserver to receive the incoming HTTP requests. You also need to specify the URL of each webhook on your webserver so that data can be sent to each one.

Webhooks workflow

With webhooks, it's important that the URL to send the webhooks to is configured. When there is data available, Nexmo sends the webhook to your application as an HTTP request. Your application should respond with an HTTP success code to indicate that it successfully received the data.

The process looks something like this:

Your App->Nexmo: Configure URL for webhook Note over Your App, Nexmo: Some time later ... Nexmo->Your App: Have some interesting data Your App->Nexmo: 200 OK

Webhooks provide a convenient mechanism for Nexmo to send information to your application for events such as an incoming call or message, or a change in call status. They can also be used to send follow-up information such as a delivery receipt which may become available some time after the request it relates to.

 Which APIs support webhooks?

Information resulting from requests to the SMS API, Voice API, Number Insight API, US Short Codes API and Nexmo virtual numbers is sent in an HTTP request to your webhook endpoint on an HTTP server.

Nexmo sends and retrieves the following information using webhooks:

API Name Webhooks usage
SMS API Sends the delivery status of your message and receives inbound SMS
Voice API Retrieves the Nexmo Call Control Objects you use to control the call from one webhook endpoint, and sends information about the call status to another
Number Insight Advanced Async API Receives complete information about a phone number
US Short Codes API Sends the delivery status of your message and receives inbound SMS

Setting webhook endpoints

Webhooks are used to deliver incoming messages and delivery receipts.

Incoming messages

To set up the webhook used for incoming messages, go to the Your Numbers  section of the Nexmo Dashboard. Click 'edit' for the virtual number and set the Callback URL.

You can also use the nexmo-cli  to set the incoming messages endpoint for an individual number.

Delivery Receipts

See the Delivery Reciepts guide in the SMS documentation.

The Number Insight Advanced API allows you to have the results of a number lookup sent synchronously or asyncronously.

Set the callback argument to a webhook URL to receive the lookup asynchronously.

See Number Insight Advanced Async for more details.

For Voice API requests, webhooks can be set at an application level, when creating a call, or in the actions in an NCCO.

Application-level webhooks

Numbers you have purchased that are connected to Nexmo applications will use the answer_url to retrieve an NCCO, and the event_url to send call status information to you.

You can set these using the Application API, in the Nexmo Dashboard  or using the Nexmo CLI  tool.

Number-level webhooks

You can set a status webhook for each number you purchase. This will be used to send events to you regarding each number.

These can be set up in the Numbers section of the Dashboard  , via the Nexmo CLI  or via the Update a Number API call (specifically, the voiceStatusCallback property).

On creating an outbound call

When making a new outbound call, you need to set the answer_url in the call to a URL containing an NCCO. Nexmo's servers will retrieve the NCCO from this endpoint and follow its instructions in handling the outbound call.

Answer URL payload

The payload for the answer_url is:

Parameter Description
to The number being called
from The number making the call
conversation_uuid The UUID of the conversation
uuid The UUID of the leg

Example URL:

/webhooks/answer?to=447700900000&from=447700900001&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789cd

Inside an NCCO

Inside an NCCO, the following action types take a webhook URL for use when that action is executed:

  • record.eventUrl - set the webhook endpoint that receives information about the recording for a Call or Conversation
  • conversation.eventUrl - set the URL to the webhook endpoint Nexmo calls asynchronously when a conversation changes state for this conversation action
  • connect.eventUrl - set the URL to the webhook endpoint Nexmo calls asynchronously when a conversation changes state for this connect action
  • input.eventUrl - set the URL to the webhook endpoint Nexmo sends the digits pressed by the callee
  • stream.streamUrl - set an array of URLs pointing to the webhook endpoints hosting the audio file to stream to the Call or Conversation

Receiving webhooks

To interact with Nexmo webhooks:

  1. Create a Nexmo account.
  2. Write scripts to handle the information sent or requested by Nexmo. Your server must respond with a success status code (any status code between 200 OK and 205 Reset Content) to inbound messages from Nexmo.
  3. Publish your scripts by deploying to a server (for local development, try Ngrok  ).
  4. Configure a webhook endpoint in the API you would like to use.
  5. Take an action (such as sending an SMS) that will trigger that webhook.

Information about your request is then sent to your webhook endpoint.

Tips for debugging webhooks

Start simple - Publish the simplest possible script that you can think of to respond when the webhook is received and perhaps print some debug information. This makes sure that the URL is what you think it is, and that you can see the output or logs of the application.

Code defensively - Inspect that data values exist and contain what you expected before you go ahead and use them. Depending on your setup, you could be open to receiving unexpected data so always bear this in mind.

Look at examples - Nexmo provides examples implemented with several technology stacks in an attempt to support as many developers as possible. For example code using webhooks see the following:

You can also check the Building Blocks section of the documentation for the API you are using.

Using Ngrok for local development

Webhooks are an unusual situation for developers; often you will work on local platforms while you're getting the details worked out, but when using webhooks your webhook URLs must be publicly accessible in order for Nexmo or another service to access them. One way to work around this problem is to use a free tool called (Ngrok)[https://ngrok.com/]. Ngrok creates a secure tunnel to your locally-running application from the outside world. To get started with Ngrok, follow these steps:

  1. Download and install Ngrok using the instructions  for your platform.
  2. Start your webserver running locally, and check which port it uses (for example, if you usually use http://localhost:3000  to access your application, then the port is 3000).
  3. Create an Ngrok tunnel to this port with a command such as ngrok http 3000.
  4. This command will show the URL of the tunnel, which will look similar to https://abcdef1.ngrok.io. Copy this URL.
  5. Go ahead and configure your Nexmo webhooks to point to this URL, and you are up and running.

Beware that each time you start up the Ngrok tunnel, you're likely to get a new URL so don't forget to update the webhooks configuration accordingly! Paid Ngrok accounts can reserve tunnel names and choose which one to use when they start up, so you can avoid having to reconfigure your webhooks.

Cool bonus feature of Ngrok: in addition to the tunnel URL displayed in the command output, you will also see a URL for the "Web Interface". The web interface offers an excellent way of examining the details of all the requests received by the tunnel and the responses returned, and is therefore a very useful debugging tool. You can also use the "Replay" button to repeat a request rather than having to send yourself lots of text messages or continuously reproduce whatever event your webhook code is responding to. These features make testing your application's response to webhooks much more convenient.

Configuring your firewall

If you restrict inbound traffic (including delivery receipts), you need to whitelist the following IP addresses in your firewall. Inbound traffic from Nexmo might come from any of the following:

  • 174.37.245.32/29
  • 174.36.197.192/28
  • 173.193.199.16/28
  • 119.81.44.0/28
  • 5.10.112.112/28