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.

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
// this line loads the library
$client = new \Twilio\Rest\Client(USERNAME, PASSWORD, ACCOUNT_SID, REGION, new \Twilio\Http\CurlClient(array(
    CURLOPT_PORT, 8443
)));
$message = $client->messages->create("+11234567890", array(
    'from' => '+10987654321',
    'body' => 'Hello World!'
));
echo $message->body;

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#

var client = new TwilioRestClient(    
      "[YOUR_ACCOUNT_SID]",    
      "[YOUR_AUTH_TOKEN]",    
      "[YOUR_ACCOUNT_SID]",    
      "2010-04-01",   
      "https://api.twilio.com:8443/");           

var result = client.SendMessage("[FROM_PHONE_NUMBER]", "[TO_PHONE_NUMBER]", "Your system is ready for the upcoming change to the Twilio API's SSL certificate. No further action is needed");

Python

from twilio.rest import TwilioRestClient

ACCOUNT_SID = [YOUR_ACCOUNT_SID]"
AUTH_TOKEN = "[YOUR_AUTH_TOKEN]"
TWILIO_NUMBER = "FROM_PHONE_NUMBER"
NUMBER_TO_TEXT = "TO_PHONE_NUMBER"

client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN, base="https://api.twilio.com:8443")
client.messages.create(from_=TWILIO_NUMBER, to=NUMBER_TO_TEXT, body="Your system is ready for the upcoming change to the Twilio API's SSL certificate. No further action is needed.")

Java

// You may want to be more specific in your imports
import java.util.*;
import com.twilio.sdk.*;
import com.twilio.sdk.resource.factory.*;
import com.twilio.sdk.resource.instance.*;
import com.twilio.sdk.resource.list.*;

public class App { 
     // Find your Account Sid and Token at twilio.com/user/account 
     public static final String ACCOUNT_SID = "[YOUR_ACCOUNT_SID]";
     public static final String AUTH_TOKEN = "[YOUR_AUTH_TOKEN]";
     
     public static void main(String[]args) throws TwilioRestException {  
      TwilioRestClient client = newTwilioRestClient(ACCOUNT_SID, AUTH_TOKEN, "https://api.twilio.com:8443");   
       
       // Build the parameters   List params = new ArrayList();   params.add(new
       BasicNameValuePair("To", "TO_PHONE_NUMBER");   
       params.add(new BasicNameValuePair("From", "FROM_PHONE_NUMBER"));   
       params.add(new BasicNameValuePair("Body", "Your system is ready for the upcoming change to the Twilio API's SSL certificate. No further action is needed."));   

       MessageFactory messageFactory = client.getAccount().getMessageFactory();   
       Message message = messageFactory.create(params);
       System.out.println(message.getSid()); 
      }
     }

Ruby

require 'rubygems' # not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# put your own credentials here
account_sid = '[YOUR_ACCOUNT_SID]'
auth_token = '[YOUR_AUTH_TOKEN]'

# set up a client to talk to the Twilio REST API
@client = Twilio::REST::Client.new account_sid, auth_token, :host => "api.twilio.com", :port => 8443

@client.account.messages.create({
  :from => 'FROM_PHONE_NUMBER',
  :to => 'TO_PHONE_NUMBER',
  :body => 'Your system is ready for the upcoming change to the Twilio API's SSL certificate. No further action is needed.'
})

Node.js

// Twilio Credentials
var accountSid = '[YOUR_ACCOUNT_SID]';
var authToken = '[YOUR_AUTH_TOKEN]';

//require the Twilio module and create a REST client
var client = require('twilio')(accountSid, authToken, 'api.twilio.com:8443');

client.messages.create({
to: "TO_PHONE_NUMBER",
from: "FROM_PHONE_NUMBER",
body: "Your system is ready for the upcoming change to the Twilio API's SSL certificate. No further action is needed."
}, function(err, message) {
console.log(message.sid);
});

 

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