Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: UsageTrigger

A UsageTrigger is a webhook that notifies your application of usage thresholds.

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.

For more information, see Usage categories in Usage Records as well as Subaccounts.

UsageTrigger properties

A UsageTrigger is represented by the following properties:

account_sid
sid<AC> Not PII

The account this trigger monitors.

callback_method
http_method Not PII

The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST.

callback_url

Twilio will make a request to this url when the trigger fires.

current_value
string Not PII

The current value of the field the trigger is watching.

date_created
date_time<rfc2822> Not PII

The date the trigger was created, given as GMT RFC 2822 format.

date_fired
date_time<rfc2822> Not PII

The date the trigger was last fired, given as GMT RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date the trigger was last updated, given as GMT RFC 2822 format.

friendly_name
string Not PII

A user-specified, human-readable name for the trigger.

recurring
enum:recurring Not PII

How this trigger recurs. Empty for non-recurring triggers. One of daily, monthly, or yearly for recurring triggers. A trigger will only fire once during each recurring period. Recurring periods are in GMT.

sid
sid<UT> Not PII

The trigger's unique Sid.

trigger_by
enum:trigger_field Not PII

The field in the UsageRecord that fires the trigger. One of count, usage, or price, as described in the UsageRecords documentation.

trigger_value
string Not PII

The value at which the trigger will fire. Must be a positive numeric value.

uri
uri Not PII

The URI for this resource, relative to https://api.twilio.com.

usage_category
enum:usage_category Not PII

The usage category the trigger watches. One of the supported usage categories.

usage_record_uri
string Not PII

The URI of the UsageRecord this trigger is watching, 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.

For more information, see CallbackUrl Request Parameters below.

Create a UsageTrigger Resource

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.

Inactive UsageTriggers will not be deleted automatically.

You need to delete triggers you no longer need. For more information, see Delete a UsageTrigger resource below.

Parameters
CallbackUrl
Required
post url PII MTL: 60 DAYS

Twilio will make a request to this url when the trigger fires.

TriggerValue
Required
post string Not PII

The trigger will fire when usage reaches this value. For convenience, you can use an offset like +30, which tells Twilio to create the UsageTrigger with its TriggerValue 30 units higher than the current usage. (just be sure to urlencode the + as %2B).

UsageCategory
Required
post enum:usage_category Not PII

The trigger will watch this usage category. One of the supported usage categories.

CallbackMethod
Optional
post http_method Not PII

Twilio will use this HTTP method when making a request to the CallbackUrl. GET or POST. The default is POST.

FriendlyName
Optional
post string Not PII

A human readable description of the new trigger. Maximum 64 characters.

Recurring
Optional
post enum:recurring Not PII

How this trigger recurs. Empty for non-recurring triggers. One of daily, monthly, or yearly for recurring triggers. A trigger will only fire once during each recurring period. Recurring periods are in GMT.

TriggerBy
Optional
post enum:trigger_field Not PII

The field in the UsageRecord that will fire the trigger. One of count, usage, or price as described in the UsageRecords documentation. The default is usage.

Example 1
Loading Code Sample...
      
      
      
      

      Fetch a UsageTrigger resource

      get
      https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json
      Parameters
      Sid
      Required
      get sid<UT> Not PII

      The usage-trigger Sid that uniquely identifies this resource

      Example 1
      Loading Code Sample...
          
          
          
          

          Read multiple UsageTrigger resources

          get
          https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers.json
          Parameters
          Recurring
          Optional
          get enum:recurring Not PII

          Only show UsageTriggers that count over this interval. One of daily, monthly, or yearly. To retrieve non-recurring triggers, leave this empty or use alltime.

          TriggerBy
          Optional
          get enum:trigger_field Not PII

          Only show UsageTriggers that trigger by this field in the UsageRecord. Must be one of: count, usage, or price as described in the UsageRecords documentation.

          UsageCategory
          Optional
          get enum:usage_category Not PII

          Only show UsageTriggers that watch this usage category. Must be one of the supported usage categories.

          Example 1
          Loading Code Sample...
              
              
              
              

              Update a UsageTrigger Resource

              post
              https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json

              Attempts a UsageTrigger's properties update and, if successful, returns the updated resource representation.

              The returned response is identical to the returned response of a GET request.

              Parameters
              CallbackMethod
              Optional
              post http_method Not PII

              The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST.

              CallbackUrl
              Optional
              post url PII MTL: 60 DAYS

              Twilio will make a request to this url when the trigger fires.

              FriendlyName
              Optional
              post string Not PII

              A user-specified, human-readable name for the trigger.

              Example 1
              Loading Code Sample...
                  
                  
                  
                  

                  Currently, you cannot update the category or value of an existing UsageTrigger. Instead, use POST to create a new UsageTrigger and use DELETE to remove an old UsageTrigger.

                  Delete a UsageTrigger resource

                  delete
                  https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json

                  UsageTrigger Callbacks

                  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.

                  For more information about Idempotence, see this wiki page.

                  Example: daily recurring UsageTrigger's idempotency token

                  ACed70abd024d3f57a4027b5dc2ca88d5b-FIRES-UTc142bed7b38c4f8186ef41a309814fd2-2012-10-04
                  

                  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 had already sent the email to your customer then you would skip sending the email, instead replying with an HTTP status code of 200.

                  For more information on test-and-set, see this wiki page.

                  Need some help?

                  We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                  Loading Code Sample...