Webhooks

What is a webhook?

A webhook  is a callback sent via HTTP to a URL of your choice. It is a simple way of enabling communication from our servers to yours. Nexmo uses webhooks to notify you about incoming calls and messages, events in calls and delivery receipts for messages.

 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:

  • 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 the webhook endpoint for the Nexmo APIs

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.

⚓️Working with the Nexmo webhooks

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 scripts must always respond with HTTP 200 to inbound messages from Nexmo.
  3. Put your scripts on your HTTP server.
  4. Send a request with the webhook endpoint set.

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

The following code examples are webhooks for the SMS API:

var app = require('express')();
app.set('port', (process.env.PORT || 5000));
app.use(require('body-parser').urlencoded({
    extended: false
}));
// Handle GET webhook
app.get('/delivery-receipt-webhook', function(req, res) {
    handleWebhook(req.query, res);
});
// Handle POST webhook
app.post('/delivery-receipt-webhook', function(req, res) {
    handleWebhook(req.body, res);
});

function handleWebhook(params, res) {
    if (!params['status'] || !params['messageId']) {
        console.log('This is not a delivery receipt');
    } else {
        //This is a DLR, check that your message has been delivered correctly
        if (params['status'] !== 'delivered') {
            console.log("Fail:", params['status'], ": ", params['err-code']);
        } else {
            console.log("Success");
          /*
            * The following parameters in the delivery receipt should match the ones
            * in your request:
            * Request - from, dlr - to\n
            * Response - message-id, dlr - messageId
            * Request - to, Responese - to, dlr - msisdn
            * Request - client-ref, dlr - client-ref
           */
        }
    }
    res.sendStatus(200);
}

app.listen(app.get('port'), function() {
    console.log('Example app listening on port', app.get('port'));
});

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