Signature validation-V3

All requests from Plivo’s Voice platform to your application server contain X-Plivo-Signature-V3, X-Plivo-Signature-Ma-V3, and X-Plivo-Signature-V3-Nonce HTTP headers. To verify that the request to your server originated from Plivo and that it was not altered en route, you may generate your own request signatures and compare them with the X-Plivo-Signature-V3 or X-Plivo-Signature-Ma-V3 HTTP headers passed by Plivo.

​

Signature generation logic

Plivo signs all HTTP requests from its servers to your application server, and assembles the request to your application server by concatenating the final request URL (the full URL with the scheme, port, and query string) and any POST parameters.

• If your request is a POST, Plivo will take all the POST parameters, sort them alphabetically by name (using Unix-style case-sensitive sorting), and append the parameter name and value pairs to the end of the URL.
• If the request is a GET, the final request URL will include all of Plivo’s request parameters appended to the query string of your original URL.

​

Example:

If your application URL is https://example.com/abcd?foo=bar and the list of Plivo POST parameters is:

- Digits:1234
- To:+15555555555
- From:+15551111111
- CallUUID:4vbcpem8-0u46-x1ha-9af1-438vc92bf374

Then the complete assembled request string would be:

- https://example.com/abcd?foo=bar.CallUuid4vbcpem8-0u46-x1ha-9af1-438vc92bf374Digits1234From+15551111111To+15555555555

​

Concatenating with nonce value

The assembled request string from this step is then appended with a randomly generated nonce string that’s unique for every request. This string is passed separately in the HTTP header X-Plivo-Signature-V3-Nonce as part of the HTTP request to your application URL.

​

Example:

If the randomly generated nonce value is

kjsdhfsd87sd7yisud2

then this is how the request string would look after appending the nonce to the previously assembled request string.

- https://example.com/abcd?foo=bar.CallUuid4vbcpem8-0u46-x1ha-9af1-438vc92bf374Caller+15551111111Digits1234From+15551111111To+15555555555.kjsdhfsd87sd7yisud2

Since nonce values are unique, they can help protect your application server from replay attacks.

​

Signing with Auth Token

The output of this step is then signed using HMAC-SHA256 and your Plivo Auth Token as the key. The resulting signed hashes are Base64-encoded and passed in HTTP headers with the request.

X-Plivo-Signature-V3 is generated using the Auth Token of the account or subaccount associated with the request entity.

For example, if the request is for an incoming call to a Plivo phone number mapped to one of your subaccounts, then that subaccount’s Auth Token will be used when generating X-Plivo-Signature-V3.

X-Plivo-Signature-Ma-V3, on the other hand, is always generated using the Auth Token of your main Plivo account.

​

Validating requests on the application server

Plivo Server SDKs include helper functions to validate incoming requests with X-Plivo-Signature HTTP headers.

​

Code

from flask import Flask, request, make_response
import plivo
from plivo import plivoxml

app = Flask(__name__)


@app.route("/speak/", methods=["GET", "POST"])
def validate_signature():
   auth_token = "<auth_token>"
   signature = request.headers.get("X-Plivo-Signature-V3")
   nonce = request.headers.get("X-Plivo-Signature-V3-Nonce")
   webhook_url = request.url
   http_method = request.method

   if http_method == "GET":
       valid_signature = plivo.utils.validate_v3_signature(
           http_method, webhook_url, nonce, auth_token, signature
       )
   elif http_method == "POST":
       params = request.form.to_dict()
       valid_signature = plivo.utils.validate_v3_signature(
           http_method, webhook_url, nonce, auth_token, signature, params
       )
   else:
       return "Method not allowed", 405

   print(f"Your webhook authentication is: {valid_signature}")

   # Return an XML answer to Plivo if the signature is valid

   if valid_signature == True:
       xml = plivoxml.ResponseElement()
       speak_params = {"loop": "3"}
       xml.add(plivoxml.SpeakElement("Hello, from Plivo", **speak_params))
       response = make_response(xml.to_string())
       response.headers["Content-type"] = "text/xml"
       print("Send XML to Plivo server")
       print(xml.to_string())
       return response, 200
   else:
       return "Bad request", 400


if __name__ == "__main__":
   app.run(host="0.0.0.0", debug=True)

When someone makes a call to a Plivo number, Plivo requests the webhook associated with this code. The code runs and returns a Speak XML element if it can authenticate the request sent. If the validation fails the call will terminate, since no XML is returned to the Plivo server.

You may also write your own request validation code by generating request signatures based on the signature generation logic and validating them against the signatures passed by Plivo in the HTTP request headers.

If you’re still using Plivo’s V2 signatures to validate requests, we highly recommend switching over to X-Plivo-Signature-V3. V3 signatures offer improved protection against manipulation of POST request payloads en route.