Monitoring Updates to Twilio REST API SSL Certificates

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 SSL Certificate update procedures to enable you, our customer, to monitor for any upcoming API SSL certificate changes.  This document is meant to be a “How To” guide to monitor for these changes.

REST API ‘s SSL Certificate Upgrade Procedures

A month in advance of any API SSL certificate change, we will post the new "to be upgraded" SSL certificate on port 8443 of all of our API endpoints. 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

For one week after the certificate has been updated, we will leave the “upgraded” certificate available on port 8443.

The month prior to the upgrade and one week after is our upgrade window.

Port 8443 will not accept HTTPS traffic outside of the aforementioned upgrade window.

How to Monitor for Changes

Based on this procedure, an organization or individual can now monitor for any upcoming API certificate change.  A simple script to monitor port 8443 will let an interested party know when an impending API certificate is coming.  If the request times out, there is no impending certificate change.  If the requests responds, a new certificate is impending and available for testing.  As stated before, the new certificate will be available in advance on port 8443.  Code connecting to port 8443 is available in subsequent “Sample Test Code” section.

Testing Your Environment

The best way to see if your environment is impacted by the certificate change is by performing a test command to our endpoint outlined above to port 8443 (i.e. https://api.twilio.com:8443). If your command successfully tests the endpoint, no changes will be needed on your end for the upcoming certificate change.

Expected Output:

<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
  <Versions firstpageuri="/?Page=0&amp;PageSize=50" numpages="1" end="1" total="2" previouspageuri="" lastpageuri="/?Page=0&amp;PageSize=50" uri="/" pagesize="50" start="0" nextpageuri="" page="0">
    <Version><Name>2008-08-01</Name><Uri>/2008-08-01</Uri><SubresourceUris><Accounts>/2008-08-01/Accounts</Accounts></SubresourceUris></Version>
    <Version><Name>2010-04-01</Name><Uri>/2010-04-01</Uri><SubresourceUris><Accounts>/2010-04-01/Accounts</Accounts></SubresourceUris></Version>
  </Versions>
</TwilioResponse>

If your command fails, then outside of syntax errors, you are likely missing our new root certificate.  We do not recommend pinning certificates.  If you or your organization are pinning root certificates, please ensure the Thawte Primary Root CA is available in your local trust store.

Sample Testing CodeHelper Libraries for Testing

PHP

<?php
require __DIR__ . '/vendor/autoload.php'; $client = new Twilio\Http\CurlClient(); $response = $client->request('GET', 'https://api.twilio.com:8443'); echo $response;

cURL

curl -X POST 'https://api.twilio.com:8443/2010-04-01/Accounts/[YOUR_ACCOUNT_SID]/Messages.json'
--data-urlencode 'To=TO_PHONE_NUMBER'
--data-urlencode 'From=FROM_PHONE_NUMBER'
--data-urlencode 'Body=Your system is ready for the upcoming change to the Twilio API SSL certificate. No further action is needed.'
-u [YOUR_ACCOUNT_SID]:[AuthToken]

C#

using System;
using Twilio.Http;

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

Python

from twilio.http.http_client import TwilioHttpClient

client = TwilioHttpClient()
response = client.request('GET', 'https://api.twilio.com:8443')
print(response)

Java

import com.twilio.http.*;

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

Ruby

require 'twilio-ruby'

@client = Twilio::REST::Client.new
response = @client.request('api.twilio.com', '8443', 'GET', 'https://api.twilio.com:8443/.json')
puts response

Node.js

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

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

 

Notifications

For routine SSL certificate updates to refresh expiring certificates, we will not send out any customer notification.  If our certificate change affects the encryption level, encryption cypher, root chain or root certificate in any way, we will send out notification via email with a month’s notice.  The update procedure will be followed on any type of update to our certificate.

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.

Have more questions? Submit a request
Powered by Zendesk