Signed Webhooks [Developer Preview]

Signed webhooks provide a method for your application to verify a request is coming from Vonage, and its payload has not been tampered with during transit.

Voice API Signed webhooks are currently offered as Developer Preview. The feature can be used in your projects for supported scenarios (see below). The following limitations apply:

a limited set of events supported,
activation can be done through Applications API request only.

Activation

Follow these steps to activate signed callbacks for your application.

Get Application

Retrieve your application data with a Get an application HTTP request using Postman or another HTTP client of your choice:

GET https://api.nexmo.com/v2/applications/YOUR_APPLICATION_ID

Copy the response body:

{
    "id": "YOUR_APPLICATION_ID",
    "name": "My app",
    "keys": {
        "public_key": "YOUR_PUBLIC_KEY"
    },
    "capabilities": {
        "voice": {
            "webhooks": {
                "event_url": {
                    "address": "https://example.com",
                    "http_method": "POST"
                },
                "fallback_answer_url": {
                    "address": "",
                    "http_method": "GET"
                },
                "answer_url": {
                    "address": "https://example.com",
                    "http_method": "GET"
                }
            }
        }
    },
    "_links": {
        "self": {
            "href": "/v2/applications/YOUR_APPLICATION_ID"
        }
    }
}

Unlike Voice API, the Applications API uses header-based API Key and Secret Authentication, which means you should use a Base64 encoded API key and secret joined by a colon in the Authorization header of the HTTP request.

Update Application

Update your application with a Update an application HTTP request:

PUT https://api.nexmo.com/v2/applications/YOUR_APPLICATION_ID

Use the response JSON from the previous step as the request body with the addition of the signed_callbacks parameter:

{
    "id": "YOUR_APPLICATION_ID",
    "name": "My app",
    "keys": {
        "public_key": "YOUR_PUBLIC_KEY"
    },
    "capabilities": {
        "voice": {
            "webhooks": {
                "event_url": {
                    "address": "https://example.com",
                    "http_method": "POST"
                },
                "fallback_answer_url": {
                    "address": "",
                    "http_method": "GET"
                },
                "answer_url": {
                    "address": "https://example.com",
                    "http_method": "GET"
                }
            },
            "signed_callbacks": true
        }
    },
    "_links": {
        "self": {
            "href": "/v2/applications/YOUR_APPLICATION_ID"
        }
    }
}

You can make a GET request from step one again to ensure the parameter is applied (it should be returned in the response).

Developer Preview limitation: if you change any parameter of your application via Dashboard, the signed_callbacks parameter will be dropped, and the feature will be inactivated, so you have to go through the activation steps again to turn it back on.

Validating Signed Webhooks

See Signed webhooks in the Messages API Concepts section. Voice signed callbacks have the same JWT in the Authorization header, which your application is supposed to validate.

Supported Events and Scenarios

At the moment, only the following events are supported:

All the other events, as well as the initial answer webhook, are still sent without the signature (Authorization header).

With this limitation, you can use the signed webhooks now for a basic voice alert or two-factor authentication scenario, using a Create an outbound call API request with an embedded NCCO:

{
  "to": [
    {
      "type": "phone",
      "number": "'$TO_NUMBER'"
    }
  ],
  "from": {
    "type": "phone",
    "number": "'$YOUR_NEXMO_NUMBER'"
  },
  "ncco": [
    {
      "action": "talk",
      "text": "Your code is '$TEMP_CODE'"
    }
  ]
}

See also the Make an outbound call with an NCCO code snippet.

Improve this page