Monitoring Updates to Twilio REST API Security Settings – Twilio Support

At Twilio, we believe in security, operational excellence, and transparency to build trust between us and our customers. To this end, we are publishing our REST API security update procedures to enable customers to monitor for any upcoming changes to certificates, TLS versions or cipher suites. This document is meant to be a “How To” guide to monitor for these changes.

REST API Security Upgrade Procedures

At least one month in advance of any REST API security change, we will post the new "to be upgraded" certificate and configuration on endpoint https://tls-test.twilio.com for all of our REST API edges.
These include, but are not exclusive to:

api.twilio.com
lookups.twilio.com
notify.twilio.com
partners.twilio.com
preview.twilio.com
taskrouter.twilio.com

How to Monitor for Changes

Customers can monitor for any upcoming security change with a simple script to check connectivity against https://tls-test.twilio.com. If the request succeeds with 200 OK, no further action is required. If there is a timeout or error message, further investigation is required to determine the cause and resolve any issues. Code snippets for connecting to this endpoint are available in the next section.

Testing Your Environment

The best way to test if your environment is impacted by a TLS or certificate change is by sending an HTTP request to our test endpoint https://tls-test.twilio.com from your production environment (or one that is identical to production). If your HTTP request succeeds, no changes will be needed on your end for the update.

Note: Be sure your environment allows outbound HTTPS traffic to domain tls-test.twilio.com and port 443.

Expected Results

If the test succeeds, you'll receive a 200 OK status code and XML or JSON output similar to this content body:

<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
   <Content>TLS connection established successfully</Content>
</TwilioResponse>

If your command fails, then outside of syntax errors, your local trust store may be missing our root certificate or your system does not support the TLS version or cipher suites enabled on the test endpoint.

Note: We do not recommend pinning certificates, but if you or your organization are pinning root certificates, please ensure the DigiCert Global Root CA is available in your local trust store.

Testing with cURL

The simplest method to test is to run this command via cURL from your production server:

curl https://tls-test.twilio.com --tlsv1.2

Testing with Twilio Helper Libraries

We strongly recommend using our official Twilio Helper Libraries and keeping them up-to-date. Our helper libraries incorporate security best practices and are able to automatically handle certificate rotations. Other security updates, such as updates in the cipher list, may impact your ability to connect to Twilio due to underlying operating system limitations, you can test the new security configuration using the code snippets listed below for each supported language:

C# (.NET Framework 4.5.1+ and .NET Core)

The following snippet is for C# helper library version >= 5.x.

For more comprehensive testing examples for .NET, see our .NET TLS Tests repository.

using System;
using Twilio.Http;

class TwilioApiTest
{
    static void Main(string[] args)
    {
            HttpClient client = new SystemNetHttpClient();
            Request request = new Request(HttpMethod.Get, "https://tls-test.twilio.com");
            Response response = client.MakeRequest(request);
            Console.Write(response.Content);
    }
}

C# (.NET Framework 3.5 - 4.5)

The following snippet is for C# helper library version >= 5.x.

For more comprehensive testing examples for .NET, see our .NET TLS Tests repository.

using System;
using Twilio.Http;
using Twilio.Http.Net35;

class TwilioApiTest
{
    static void Main(string[] args)
    {
            HttpClient client = new WebRequestClient();
            Request request = new Request(HttpMethod.Get, "https://tls-test.twilio.com");
            Response response = client.MakeRequest(request);
            Console.Write(response.Content);
    }
}

Java

The following snippet is for Java helper library version >= 7.x.

import com.twilio.http.*;

public class TwilioApiTest {
    
    public static void main(String[] args) {
        NetworkHttpClient client = new NetworkHttpClient();
        Request request = new Request(HttpMethod.GET, "https://tls-test.twilio.com/");
        Response response = client.makeRequest(request);
        System.out.print(response.getContent());
    }
}

Node.js

The following snippet is for Node.js helper library version >= 3.x.

var RequestClient = require('twilio/lib/base/RequestClient');

var client = new RequestClient();
client.request({
    method: 'GET',
    uri: 'https://tls-test.twilio.com'
}).
then(function(response){
  console.log(response.body);
});

PHP

The following snippet is for PHP helper library version >= 5.x.

<?php
require __DIR__ . '/vendor/autoload.php';

$client = new Twilio\Http\CurlClient();
$response = $client->request('GET', 'https://tls-test.twilio.com');
echo $response;

Python

The following snippet is for Python helper library version >= 3.x.

from twilio.http.http_client import TwilioHttpClient

client = TwilioHttpClient()
response = client.request('GET', 'https://tls-test.twilio.com')
print(response)

Ruby

The following snippet is for Ruby helper library version >= 5.x.

require 'twilio-ruby'

@client = Twilio::REST::Client.new
response = @client.request('tls-test.twilio.com', '443', 'GET', 'https://tls-test.twilio.com')
puts response

Notifications

For routine updates to refresh expiring certificates, we will not send out any customer notification. However, if our security change affects the encryption level, encryption cipher, root chain or root certificate in any way, we will send out notification via Twilio's change log with at least one month’s notice. We recommend you subscribe to the change log RSS Feed to be notified of these changes. This procedure will be followed on any type of update to our REST API security configuration.

We hope this stated policy will help our customers stay operationally excellent and increase your trust in Twilio.

If you have any questions, please contact Customer Support.