A UsageTrigger is a webhook that notifies your application of usage thresholds.
(information)
Info
Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.
(warning)
Warning
It can take some amount of time for the data used by usage triggers to be reflected in the UsageTriggers evaluations.
Using this resource, you can make or update a new UsageTrigger, fetch information about an existing UsageTrigger or multiple UsageTriggers, or delete an existing UsageTrigger.
You can configure UsageTriggers to recur daily, monthly, or yearly. UsageTriggers are evaluated frequently — about once a minute — to provide timely information to your application.
You can also set UsageTriggers for any usage category. For example, you can create a single UsageTrigger to track daily usage. In this case, a UsageTrigger notifies your application when your cost exceeds a set daily amount. If used together with Subaccounts created for each end-user, then a UsageTrigger would notify your application that a specific user has exceeded an allocated monthly usage.
The frequency of a recurring UsageTrigger. Can be: daily, monthly, or yearly for recurring triggers or empty for non-recurring triggers. A trigger will only fire once during each period. Recurring times are in GMT.
The URI of the UsageRecord resource this trigger watches, relative to https://api.twilio.com.
CallbackUrl requests
When an account's usage category crosses a UsageTrigger's TriggerValue during the specified interval, then Twilio makes a request to the CallbackUrl using the HTTP method CallbackMethod with the CallbackUrl Request parameters.
Twilio guarantees that a UsageTrigger will fire once (at most) during its recurring interval and will quickly retry the callback URL three times after a 5xx error.
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers.json
Each account can create up to 1,000 UsageTriggers. If UsageTrigger creation is successful, Twilio will respond with a representation of the new trigger.
(warning)
Warning
Inactive UsageTriggers will not be deleted automatically.
The usage value at which the trigger should fire. For convenience, you can use an offset value such as +30 to specify a trigger_value that is 30 units more than the current usage value. Be sure to urlencode a + as %2B.
The frequency of a recurring UsageTrigger. Can be: daily, monthly, or yearly for recurring triggers or empty for non-recurring triggers. A trigger will only fire once during each period. Recurring times are in GMT.
The field in the UsageRecord resource that should fire the trigger. Can be: count, usage, or price as described in the UsageRecords documentation. The default is usage.
Possible values:
countusageprice
Create a new UsageTrigger with parameters
Node.js
Python
C#
Java
PHP
Ruby
curl
_14
// Download the Node helper library from twilio.com/docs/node/install
_14
// These consts are your accountSid and authToken from https://www.twilio.com/console
_14
// To set up environmental variables, see http://twil.io/secure
The frequency of recurring UsageTriggers to read. Can be: daily, monthly, or yearly to read recurring UsageTriggers. An empty value or a value of alltime reads non-recurring UsageTriggers.
As soon as the usage value of a UsageTrigger exceeds the TriggerValue, the trigger will fire and Twilio will make an asynchronous HTTP request to the UsageTrigger's CallbackUrl. This request will typically take place within a minute of exceeding the usage threshold.
CallbackUrl request parameters
Twilio will pass the following parameters to the UsageTrigger's CallbackUrl:
Parameter
Description
AccountSid
Your Twilio account id. It is 34 characters long and always starts with the letters AC
UsageTriggerSid
Unique identifier of the fired UsageTrigger.
DateFired
Date when the UsageTrigger fired, in GMT.
Recurring
How the fired UsageTrigger recurs. For non-recurring UsageTriggers: leave empty. For recurring UsageTriggers: choose daily, monthly, or yearly.
UsageCategory
Usage category watched by the UsageTrigger: choose from supported usage categories.
TriggerBy
UsageRecord field that fires the UsageTrigger: choose from count, usage, or price.
TriggerValue
Value at which the UsageTrigger fired.
CurrentValue
The current value of the usage watched by the UsageTrigger.
UsageRecordUri
URI of the UsageRecord that this UsageTrigger watched when it fired.
IdempotencyToken
A random token generated by Twilio and guaranteed to be unique for this particular firing of this UsageTrigger.
Best practices with UsageTrigger callbacks
When implementing a handler for UsageTrigger's CallbackUrl, your handler may receive HTTP requests more than once. Services that handle duplicate requests and return the same response are called Idempotence.
We give you an IdempotencyToken that is unique for each Usage Trigger callback.
You can keep track of your IdempotencyToken to properly handle requests to your service and prevent a request from performing the same operation twice.
For example, your callback service may send billing notifications via email. For the best possible customer experience, you would want your customers only to receive the billing notification email once.
You can follow the test-and-set (external link) pattern to implement idempotent services. In short, you would test for the existence of the IdempotencyToken before processing your application's logic. This allows your application to handle existing tokens and choose the next appropriate step.
In the email example, you would have already sent the email to your customer then you would skip sending the email, instead replying with an HTTP status code of 200.