UsageTriggers are webhooks that notify your application of usage thresholds. You can set UsageTriggers for any usage category. UsageTriggers are evaluated frequently - about once a minute - so they can provide timely information to your application. In addition, UsageTriggers can be configured to recur daily, monthly, or yearly so you can create a single UsageTrigger that will track usage every day.
For instance, a UsageTrigger could notify your application if usage cost starts to exceed what you would expect in a day. Or, used in combination with Subaccounts created for each of your end-users, UsageTriggers could notify your application that a particular user has exceeded their allocated monthly usage.
The resource supports POST to make a new UsageTrigger or update an existing UsageTrigger, GET to retrieve existing UsageTriggers, and DELETE to remove an existing trigger.
UsageTriggers are scoped under /Usage, and are referenced by their Sid.
/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{UsageTriggerSid}
A UsageTrigger is represented by the following properties:
| Property | Description |
|---|---|
| Sid | The trigger's unique Sid. |
| DateCreated | The date the trigger was created, given as GMT RFC 2822 format. |
| DateUpdated | The date the trigger was last updated, given as GMT RFC 2822 format. |
| AccountSid | The account this trigger monitors. |
| FriendlyName | A user-specified, human-readable name for the trigger. |
| Recurring | 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. |
| UsageCategory | The usage category the trigger watches. One of the supported usage categories. |
| TriggerBy | The field in the UsageRecord that fires the trigger. One of count, usage, or price, as described in the UsageRecords documentation. |
| TriggerValue | The value at which the trigger will fire. Must be a positive numeric value. |
| CurrentValue | The current value of the field the trigger is watching. |
| UsageRecordUri | The URI of the UsageRecord this trigger is watching, relative to https://api.twilio.com. |
| CallbackUrl | Twilio will make a request to this url when the trigger fires. |
| CallbackMethod | The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST. |
| DateFired | The date the trigger was last fired, given as GMT RFC 2822 format. |
| Uri | The URI for this resource, relative to https://api.twilio.com. |
As soon as the account's usage
category crosses the UsageTrigger's
TriggerValue during the interval specified, then Twilio will make a
request to the CallbackUrl using the HTTP method CallbackMethod
with the parameters described below.
Twilio guarantees that a UsageTrigger will fire at most once during its
recurring interval, and will retry the callback URL 3 times quickly
after a 5xx error.
Returns a repesentation of the UsageTrigger, including the properties above.
Tries to update the UsageTrigger's properties, and returns the updated resource representation if successful. The returned response is identical to that returned when making a GET request.
You may specify one or more of the following parameters to update this UsageTrigger's properties. Note that POST parameters are case-sensitive.
| Parameter | Description |
|---|---|
| FriendlyName | A human-readable name for the trigger. |
| CallbackUrl | Twilio will make a request to this url when the trigger fires. |
| CallbackMethod | The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST. |
Note that it's not currently possible to update the category or value of an existing UsageTrigger. Instead, POST to create a new UsageTrigger, and DELETE to remove the old one.
Change the FriendlyName and CallbackUrl.
Not supported.
Delete this UsageTrigger.
If successful, Twilio will return an HTTP 204 response with no body.
The list resource for all UsageTriggers:
/2010-04-01/Accounts/{AccountSid}/Usage/Triggers
Returns a list of UsageTrigger resource representations. The list includes paging information.
By default, all UsageTriggers are returned. You can filter the list by specifying one or more query parameters. Note that the query parameters are case-sensitive:
| Parameter | Description |
|---|---|
| Recurring | 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. |
| UsageCategory | Only show UsageTriggers that watch this usage category. Must be one of the supported usage categories. |
| TriggerBy | 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. |
Creates a new UsageTrigger. Each account can create up to 1,000 UsageTriggers. Currently, UsageTriggers that are no longer active are not deleted automatically. Use DELETE to delete triggers you no longer need.
Your request must include the following parameters:
| Parameter | Description |
|---|---|
| UsageCategory | The trigger will watch this usage category. One of the supported usage categories. |
| TriggerValue | 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). |
| CallbackUrl | Twilio will make a request to this url when the trigger fires. |
Your request may include the following parameters:
| Parameter | Description |
|---|---|
| FriendlyName | A human readable description of the new trigger. Maximum 64 characters. |
| TriggerBy | 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. |
| Recurring | To make a recurring trigger that counts over its recurring interval, set this to one of: daily, monthly, or yearly. Omit this to create a non-recurring trigger. |
| CallbackMethod | Twilio will use this HTTP method when making a request to the CallbackUrl. GET or POST. The default is POST. |
If successful, Twilio responds with a representation of the new trigger.
Create a new UsageTrigger that will fire when 1,000 SMS messages have been sent.
Not Supported.
Not Supported.
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 fire within a minute of exceeding the usage threshold.
The parameters Twilio passes to the UsageTrigger's CallbackUrl are
as follows:
| Parameter | Description |
|---|---|
| AccountSid | Your Twilio account id. It is 34 characters long, and always starts with the letters AC. |
| UsageTriggerSid | The unique identifier of the UsageTrigger that fired. |
| DateFired | When the UsageTrigger fired, in GMT. |
| Recurring | How the UsageTrigger that fired recurs. Empty for non-recurring UsageTriggers. One of daily, monthly, or yearly for recurring UsageTriggers. |
| UsageCategory | The usage category the UsageTrigger watches. One of the supported usage categories. |
| TriggerBy | The field in the UsageRecord that fires the UsageTrigger. One of count, usage, or price as described in the UsageRecords documentation. |
| TriggerValue | The value at which the UsageTrigger will fire. |
| CurrentUsageValue | The current value of the usage the UsageTrigger is watching. |
| UsageRecordUri | The URI of the UsageRecord this UsageTrigger was watching when it fired. |
| IdempotencyToken | A random token generated by Twilio, and guaranteed to be unique for this particular firing of this UsageTrigger. See Best Practices with Usage Trigger Callbacks. |
When implementing a handler for UsageTrigger's CallbackUrl it is possible that your handler may receive HTTP requests more than once. Services that handle duplicate requests and return the same response are called idempotent. We give you an IdempotencyToken that is unique for each Usage Trigger callback.
daily Usage Trigger's IdempotencyToken fired on 2012-10-04:ACed70abd024d3f57a4027b5dc2ca88d5b-FIRES-UTc142bed7b38c4f8186ef41a309814fd2-2012-10-04
You can keep track of the IdempotencyToken to properly handle requests to your service and prevent them from performing same operation twice. For instance, your callback service may send billing notifications via email. For the best possible customer experience, you would want your customer's to only receive the billing notification email once.
You can follow the test-and-set 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 already 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 just skip sending the email and reply with an HTTP status code of 200.