Twilio has a feature called Usage Triggers, which can be set to send a webhook to a callback URL that you specify when predefined usage criteria are met. Usage Triggers have many uses, but this FAQ is primarily concerned with a single, very powerful, use case: protecting against fraud and coding mistakes.

Subaccount "Circuit Breaker" Script

This script is designed to make a subaccount suspend itself in response to a set Usage Trigger firing a webhook. Why would you want to do this? In some cases suspending a subaccount based on high, unexpected usage can be a good thing. Humans aren't always able to react to these types of events quickly enough, so taking a project offline might be a better option than allowing undesired usage to continue. A suspended subaccount can be unsuspended.

Setting up a subaccount

1. In order for this script to work, you need to have a subaccount.
2. Copy down the Account SID and Auth Token for the subaccount.

Setting up the script

To set up the script, deploy the following code to a server that runs PHP and can be reached by the webhook that Twilio will send. Make sure you make these modifications first:

1. Paste the Subaccount's Account SID and Auth Token into their respective places.
2. Modify the $url to be the future location of the file, once deployed.

Also be sure that you:

• Have included the Twilio PHP Helper Library.
• Have some way of knowing when this script triggers. For the sake of simplicity, this example doesn't send an alert via email, but you should consider sending yourself an email to let you know that your subaccount has been suspended. Twilio will not alert you when a subaccount is suspended by the REST API.

<?php
/** * Be sure to include the official Twilio PHP Helper Library, which can be found at:
* https://github.com/twilio/twilio-php 
*/ 

require_once('Services/Twilio.php');

/* The Account SID for the Subaccount */
$SUBACCOUNT_SID = 'ACXXXXXXX';
$SUBACCOUNT_AUTH_TOKEN = 'YYYYYYYYY'; // The Auth Token for the Subaccount

/** 
* The callback URL. Basically, the public address of this file. This is used for the Request Validation further down. 
* You can also set this value dynamically with information from your environment. 
* It's important to use 'https' because Twilio's Request Validation requires SSL. 
*/ 

$url = 'https://example.com/circuit-breaker.php';

/** 
* Suspending a subaccount is a scary thing, so we're going to use Twilio's Request Validation to make sure the webhook is actually coming from Twilio. 
* You can learn more about Twilio's Request Validation here: 
* http://www.twilio.com/docs/security#validating-requests 
*/ 

$validator = new Services_Twilio_RequestValidator($SUBACCOUNT_AUTH_TOKEN); 
$signature = $_SERVER["HTTP_X_TWILIO_SIGNATURE"];

if ($validator->validate($signature, $url, $_POST)) {

    error_log("Confirmed to have come from Twilio. {$_POST['IdempotencyToken']}"); 

    $client = new Services_Twilio($SUBACCOUNT_SID, $SUBACCOUNT_AUTH_TOKEN);

    /** 
    * This is the code to suspend the account. 
    * Please note, you SHOULD NOT edit this code to make 'suspended' into 'closed'. 
    * Account suspension is reversible, closing an account is NOT reversible. 
    */ 

    /* Again, NOT 'closed' */
    $client->account->update(array('Status' => 'suspended')); 

    /** 
    * You'll probably want to put some code here that alerts you when your subaccount has been suspended. Twilio won't alert you when you suspend an account via the API. 
    */ 

}

Setting up the Usage Trigger

Now that the script which receives the webhook is set up, we will need to create the Usage Trigger that fires the webhook. Here is an example of how you could use cURL to set a Usage Trigger:

$ curl POST -i https://api.twilio.com/2010-04-01/Accounts/{SubaccountAccountSID}/Usage/Triggers.json \ -d "FriendlyName=Suspend if subaccount uses more than $30 per-day" \ -d "Recurring=daily" \ -d "UsageCategory=totalprice" \ -d "TriggerBy=price" \ -d "TriggerValue=+30" \ -d "CallbackUrl=https://example.com/circuit-breaker.php" \ -u "{SubaccountAccountSID}:{SubaccountAuthToken}"

Reactivating your subaccount

Since this script is going to be doing something with significant consequences, it's a good idea to test this script and make sure that you understand how it works. During testing you'll need to reactivate your subaccount.

For help, please see our API docs and sample code here: Re-activate a suspended subaccount.

Things to watch out for

If you bought many phone numbers at the same time, those phone numbers will be billed at the same time in the future. If your trigger is based on total price, make sure that your limit is high enough that the normal phone number renewal doesn't suspend your project.