Soracom Air for Cellular
Event Handler
Overview
The Event Handler feature is a service that allows you to build automations based on SIM events, such when a SIM status changes or when its data usage exceeds a particular threshold, in order to send email notifications, throttle or disable a SIM, execute a webhook, and so on. Event handlers can be applied to a single subscriber, a SIM that contains one or more subscriptions, a group of SIMs, or to all SIMs in your account.
Parameters
Each event handler consists of the following configuration parameters:
- Name and Description - Any name or description to identify the event handler.
- Target - Defines which SIMs or subscribers the event handler should apply to.
- Rule - Defines a condition that should be evaluated. When this condition is met, the actions will be performed.
- One or more Actions - Defines what actions should be performed when the event handler rule condition is met.
- Status - Enables or disables the event handler.
You can also use Variables with certain actions in order to dynamically change the value of the action parameter, such as using ${simId}
to include the SIM ID of the matched SIM in an email notification or webhook.
Limitations
- If you configure multiple event handlers and their respective rule conditions are met at the same time, the actions of both event handlers will be executed.
- When the target of an event handler is set as a group, the rule condition will be evaluated for each individual SIM or subscriber belonging to the group, rather than to all SIMs or subscribers collectively.
- Each event handler is limited to a maximum of 5 actions.
- Each Soracom account is limited to the following number of event handler configurations:
Target | Limit |
---|---|
Subscriber | 10 per subscriber |
SIM | 10 per SIM |
Group | 10 per group |
Operator | 10 total |
If you require higher limits when configuring event handlers, please contact us.
Configuration
Targets
The event handler Target defines which SIMs or subscribers should be included. This allows you to control whether an event handler configuration should apply to a single SIM or subscriber, a group of SIMs or subscribers, or to all SIMs or subscribers in your account.
- Subscriber - Matches a single subscriber in your account. The
IMSI
of the subscriber is required. - SIM - Matches a single SIM in your account, which itself may contain one or more Subscription Containers. The
SIM ID
of the SIM is required. - Group - Matches one or more SIMs or subscribers in your account, which belong to a particular group. The
Group ID
of the group is required. - Operator - Matches all SIMs or subscribers in your account.
Note: The Subscriber target does not apply to planP1, planX1, planX2, planX3, plan-US-max, or plan-US-NA subscription containers. If you want to configure an event handler to target a subscription container, use the SIM, Group, or Operator targets instead.
Rules
The event handler Rule defines a condition that will be evaluated for the specified target. When the rule condition is met, the action(s) in the event handler will be performed. The available rules depend on which Target you select.
Rules that monitor data traffic are not evaluated in real time. There may be up to a 5-minute delay between the time your data usage exceeds the threshold, and when the configured action is triggered. Data usage that occurs in this window cannot be prevented and customers will still be responsible for payment of data usage fees.
-
Available rules for Subscriber, Group, and Operator targets:
- Subscriber first traffic - Executes when a subscriber sends or receives data for the first time after the event handler is created.
- Subscriber Daily traffic - Executes when a subscriber's daily data usage exceeds a specified value.
- Subscriber Monthly traffic - Executes when a subscriber's monthly data usage exceeds a specified value.
- Subscriber Cumulative traffic - Executes when a subscriber's lifetime cumulative data usage exceeds a specified value.
- Subscriber status attribute - Executes when a subscriber's status changes and (optionally) matches a specified source (before) and/or target (after) value.
- Subscriber speed class attribute - Executes when a subscriber's speed class changes and (optionally) matches a specified value.
- Subscriber expired - Executes when a subscriber expires based on its Expiration settings.
- Subscriber IMEI mismatched - Executes when the IMEI of the device using the subscriber does not match the subscriber's IMEI Lock settings.
Note: The Subscriber rules do not apply to planP1, planX1, planX2, planX3, plan-US-max, or plan-US-NA subscription containers. If you want to use rule that targets a subscription container, use one of the SIM, Group, or Operator rules below instead.
-
Available rules for SIM, Group, and Operator targets:
- Sim Daily total traffic - Executes when a SIM's total daily data usage across all of its subscriptions exceeds a specified value.
- Sim Monthly total traffic - Executes when a SIM's total monthly data usage across all of its subscriptions exceeds a specified value.
- Sim Cumulative total traffic - Executes when a SIM's total lifetime cumulative data usage across all of its subscriptions exceeds a specified value.
- Sim status attribute - Executes when a SIM's status changes and (optionally) matches a specified source (before) and/or target (after) value.
- Sim speed class attribute - Executes when a SIM's speed class changes and (optionally) matches a specified value.
- Sim expired - Executes when a SIM expires based on its Expiration settings.
- Sim subscription status - Executes when a SIM's Subscription Containers status changes and (optionally) matches a specified value.
- Sim IMEI mismatched - Executes when the IMEI of the device using the SIM does not match the SIM's IMEI Lock settings.
-
Available rules for Group and Operator targets:
- Daily total traffic - Executes when the total daily data usage across all SIMs and subscriptions exceeds a specified value.
-
Monthly total traffic - Executes when the total monthly data usage across all SIMs and subscriptions exceeds a specified value.
When using one of the above rules with a Group target, if a SIM is removed from the group in the middle of the Event Handler's daily or monthly period, any data usage that occurred prior to removal will still be counted toward that group's total traffic. Similarly, if a SIM is added to the group in the middle of the period, any previous data usage before the change will not be counted.
-
Available rules for the Operator target:
- Monthly bill amount - Executes when the current month's bill total exceeds a specified value.
The monthly bill total is not calculated in real time. There may be up to a 24-hour delay between the time when your service usage exceeds the threshold, and when the monthly bill total is updated and the configured action is triggered. Usage charges that exceed the defined amount in this window cannot be prevented and customers will still be responsible for payment of these charges.
- Monthly bill amount - Executes when the current month's bill total exceeds a specified value.
In addition to selecting one of the above rules, you must also specify when the rule should be checked again using the Re-evaluate parameter. After the rule condition is met, this parameter defines how long the event handler should wait before it evaluates the rule again. You can configure longer intervals in order to prevent the event handler from executing actions too frequently. You can also specify the Offset parameter to add an additional delay, in minutes.
Re-evaluate | The event handler will check the rule again... |
---|---|
Immediately | right away |
Beginning of next month | at the beginning of the next month |
Beginning of next day | at the beginning of the next day (at 00:00 UTC) |
After one day | one day (24 hours) later |
Never | never (the rule will not be checked again) |
By default, when the event handler Target includes multiple subscribers (such as setting a SIM, Group, or Operator target), the Rule will be applied to each subscriber individually. For example, you can use the Sim Monthly total traffic rule to receive an email notification when a SIM uses too much data within any given month. By setting the re-evaluate parameter to Beginning of next month, once a SIM exceeds the data usage threshold, the event handler will wait until the following month before it checks that SIM's monthly data usage again. During that time, the event handler will still check the data usage of other SIMs in the target, ensuring that you will still receive additional emails if other SIMs use too much data, which may be useful for identifying which devices should be inspected for abnormal behavior.
If you prefer the action to be performed only once for the entire target regardless of which SIM or subscriber triggers the rule, you can check the Do not execute again until next re-evaluation option to suppress additional actions. In the example above, enabling this option will result in sending an email when a SIM exceeds the data usage threshold, but without sending any other emails even if other SIMs also use too much data. This may be useful in identifying trends, such as how quickly a SIM reaches a particular data usage amount.
Actions
The event handler Action defines one or more actions to perform once the Rule condition is met. You can specify up to 5 actions for each event handler configuration.
-
Actions for sending emails:
- Send email - Send an email to a specified email address.
- Send email to Operator - Send an email to the Operator email address.
-
Actions for changing a SIM's properties:
- Activation - Set the SIM's status to Active.
- Deactivation - Set the SIM's status to Inactive.
- Standby - Set SIM's status to Standby.
- Suspend - Set SIM's status to Suspended.
- Change speed class - Change the SIM's speed class.
-
Actions for calling external actions:
- Execute web request - Execute a specified HTTP request.
- Invoke AWS Lambda - Invoke a specified AWS Lambda function.
For each action, you must also specify the timing of when the action should be performed using the Run parameter. When the rule condition is met, this parameter defines how long the event handler should wait before performing the action. You can use this parameter to add a delay between when the rule is matched and when the action is performed. You can also specify the Offset to add an additional delay, in minutes.
Run | The event handler will perform the action... |
---|---|
Immediately | right away |
Beginning of next month | at the beginning of the next month |
Beginning of next day | at the beginning of the next day (at 00:00 UTC) |
After one day | one day (24 hours) later |
Never | never (do not perform the action) |
Variables
When using an event handler to send an email or call an external action, you can customize the contents of the action, such as specifying the subject and body of an email, or the payload of a webhook or the parameters of a Lambda function call. In many cases, you may want to include details about the particular SIM and the rule condition that triggered the action. By using the following Variables directly inside the action parameters, the event handler will fill in the corresponding value.
${imsi}
- The IMSI of the subscriber that met the rule condition.${simId}
- The SIM ID of the SIM that met the rule condition.${operatorId}
- The Operator ID that the SIM or subscriber is registered to.${coverage}
- The coverage type that the SIM or subscriber is registered to (g
for Global coverage, orjp
for Japan coverage).${date}
- The date that the rule condition is met (format:yyyy/m/d
).${year}
- The year that the rule condition is met (format:yyyy
).${month}
- The month that the rule condition is met (format:m
).${day}
- The day that the rule condition is met (format:d
).${tags.<key>}
- The value of a specific tag belonging to the SIM, such as${tags.name}
for the SIM name, or${tags.myCustomTag}
for a custom tag with the tag namemyCustomTag
that you have set.
When using the Subscriber status attribute, Sim status attribute, Subscriber expired, or Sim expired rules, you can also use these variables in the actions:
${oldStatus}
- The SIM or subscriber's previous status.${newStatus}
- The SIM or subscriber's current status.
Similarly, when using the Subscriber speed class attribute or Sim speed class attribute rules, you can use these variables in the actions:
${oldSpeedClass}
- The SIM or subscriber's previous speed class.${newSpeedClass}
- The SIM or subscriber's current speed class.
The Sim subscription status rule contains additional variables useful for checking the Subscription Container status:
${subscription}
- The name of the subscription container being added to the SIM.${otaStatus}
- The delivery status of the subscription container (one of the following:started
,finished
, orfailed
).${imsi}
- The IMSI of the newly added subscription container, or of the original plan01s or plan-US subscription, based on the OTA status:- If the OTA status is
started
orfailed
, this variable will return the IMSI of the plan01s or plan-US subscription. - If the OTA status is
finished
, this variable will return the IMSI of the newly added subscription container.
- If the OTA status is
${primaryImsi}
- The IMSI of the original plan01s or plan-US subscription.
When using the Monthly bill amount rule, you can use the following variables in the actions:
${operatorId}
- The Operator ID where the billing alert occurred.-
${coverage}
- The coverage type where the billing alert occurred (g
for Global coverage, orjp
for Japan coverage).
${limitTotalAmount}
- The bill alert threshold that was exceeded.${currentTotalAmount}
- The actual current monthly bill amount, at the time the billing alert was triggered.
Variables can be used in the following action parameters:
- Send email and Send email to Operator actions:
- Title
- Message
- Execute web request action:
- URL
- Headers
- Body
- Invoke AWS Lambda action:
- parameter1 value
- parameter2 value
- parameter3 value
- parameter4 value
- parameter5 value
Creating an Event Handler
-
Login to the User Console. From the Menu, open the Event Handler screen.
-
Click the Create Event button.
-
Enter the event handler configuration parameters:
- Name (required) - A name that uniquely identifies the event handler.
- Description (optional) - A brief description that describes the behavior of the event handler.
- Target (required) - The subscribers that the event handler should be applied to.
- Rule (required) - The condition that must be met in order for the event handler configuration to execute its actions.
- Action (one or more required) - One or more actions to perform when an event handler configuration's rule condition is met.
- Active - Enables or disables the event handler.
- Click the Create button.
Editing an Event Handler
-
Login to the User Console. From the Menu, open the Event Handler screen.
-
From the list of event handlers, click the name of the event handler that you want to edit.
-
Enter the event handler configuration parameters.
- Click the Update button.
Deleting an Event Handler
-
Login to the User Console. From the Menu, open the Event Handler screen.
-
From the list of event handlers, click the for the event handler you want to delete, then click the Delete button.
-
Click the Delete button again to confirm.
Advanced Configuration
Configuring an event handler can also be done using either the Soracom API or Soracom CLI. Each event handler configuration is defined using a JSON object, which contains the Target, Name and Description, Rule, Action, and Status properties.
Configuration Structure
{
"name": "My event handler name",
"description": "My event handler description",
"targetImsi": "295050012345678", // match a single subscriber
"targetSimId": "8942310000012345678", // match a single SIM
"targetGroupId": "abcdef00-0000-0000-0000-000012345678", // match a group of SIMs or subscribers
"targetOperatorId": "OP0012345678", // match all SIMs or subscribers
"ruleConfig": {
"type": "ruleType",
"properties": {
"inactiveTimeoutDateConst": "IMMEDIATELY",
"inactiveTimeoutOffsetMinutes": "0",
// ...additional rule parameters
}
},
"actionConfigList": [
{
"type": "actionType",
"properties": {
"key": "value",
// ...additional action parameters
}
},
// ...additional actions
],
"status": "active"
}
Event Handler Parameters
Regardless of which rule or actions you want to configure, all event handler configurations will contain the following parameters:
- name (string, required) - A unique name for the event handler.
- description (string, optional) - A brief description for the event handler.
- targetImsi (string, required) - The IMSI of a single subscriber.
- targetSimId (string, required) - The SIM ID of a single SIM.
- targetGroupId (string, required) - The Group ID of a group.
- targetOperatorId (string, required) - Your Operator ID.
- ruleConfig (object, required) - The rule configuration.
- type (string, required) - The rule to use.
- properties (object, required) - The settings for the rule. The attributes within this object depend on what rule you use. See the Rule Parameters below.
- actionConfigList (array of objects, required) - An array of actions to perform. Each action will consist of:
- type (string, required) - The action to perform.
- properties (object, required) - The settings for the action. The attributes within this object depend on what action you use. See Action Parameters below.
- status (string, required) - Enables or disables the event handler. Valid options:
"active"
or"inactive"
.
Only one of targetImsi, targetSimId, targetGroupId, and targetOperatorId needs to be specified.
Rule Parameters
Each event handler's ruleConfig parameter should follow one of the following rule schemas.
Execute actions when a subscriber sends or receives data for the first time:
- type (string, required) -
SubscriberFirstTrafficRule
- properties (object, required) - The settings for the rule.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
- runOnceAmongTarget (boolean, optional) - See Additional Rule Properties below.
Execute actions based on a SIM or subscriber's data usage, or total data usage across all SIMs and subscribers:
- type (string, required) - The data usage rule. Valid options:
SubscriberDailyTrafficRule
- Matches when a subscriber's daily data usage exceeds a specified value.SubscriberMonthlyTrafficRule
- Matches when a subscriber's monthly data usage exceeds a specified value.SubscriberCumulativeTrafficRule
- Matches when a subscriber's lifetime cumulative data usage exceeds a specified value.SimDailyTotalTrafficRule
- Matches when a SIM's total daily data usage across all of its subscriptions exceeds a specified value.SimMonthlyTotalTrafficRule
- Matches when a SIM's total monthly data usage across all of its subscriptions exceeds a specified value.SimCumulativeTotalTrafficRule
- Matches when a SIM's total lifetime cumulative data usage across all of its subscriptions exceeds a specified value.DailyTotalTrafficRule
- Matches when the total daily data usage across all SIMs and subscriptions exceeds a specified value.MonthlyTotalTrafficRule
- Matches when the total monthly data usage across all SIMs and subscriptions exceeds a specified value.
- properties (object, required) - The settings for the rule.
- limitTotalTrafficMegaByte (integer in MB, required) - Execute action(s) when data usage exceeds this value.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
- runOnceAmongTarget (boolean, optional) - See Additional Rule Properties below.
When using a data usage rule, the inactiveTimeoutDateConst parameter cannot be set as IMMEDIATELY
.
Execute actions based on a SIM or subscriber's
status
(active
, inactive
, etc.):
- type (string, required) -
SubscriberStatusAttributeRule
orSimStatusAttributeRule
- properties (object, required) - The settings for the rule.
- sourceStatus (string or
null
, optional) - Execute action(s) when the status is changed from this value. Valid options:null
or not set - Matches anytime a SIM or subscriber's status changes, regardless of the old status.ready
- Matches when a SIM or subscriber's status changes from Ready.active
- Matches when a SIM or subscriber's status changes from Active.inactive
- Matches when a SIM or subscriber's status changes from Inactive.standby
- Matches when a SIM or subscriber's status changes from Standby.suspended
- Matches when a SIM or subscriber's status changes from Suspended.terminated
- Matches when a SIM or subscriber's status changes from Terminated.
- targetStatus (string or
null
, optional) - Execute action(s) when the status is changed to this value. Valid options:null
or not set - Matches anytime a SIM or subscriber's status changes, regardless of the new status.ready
- Matches when a SIM or subscriber's status changes to Ready.active
- Matches when a SIM or subscriber's status changes to Active.inactive
- Matches when a SIM or subscriber's status changes to Inactive.standby
- Matches when a SIM or subscriber's status changes to Standby.suspended
- Matches when a SIM or subscriber's status changes to Suspended.terminated
- Matches when a SIM or subscriber's status changes to Terminated.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
- runOnceAmongTarget (boolean, optional) - See Additional Rule Properties below.
- sourceStatus (string or
Execute actions based on a SIM's Subscription Container status (started
, finished
, etc.):
- type (string, required) -
SimSubscriptionStatusRule
- properties (object, required) - The settings for the rule.
- targetStatus (string or
null
, optional) - Execute action(s) when the status is changed to this value. Valid options:null
or not set - Matches anytime a SIM's subscription container status changes, regardless of the new status.started
- Matches when a subscription container delivery is initiated.finished
- Matches when a subscription container is successfully delivered.failed
- Matches when a subscription container delivery failed.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
- runOnceAmongTarget (boolean, optional) - See Additional Rule Properties below.
- targetStatus (string or
Execute actions based on a SIM or subscriber's
speed class
(s1.minimum
, s1.standard
, etc.):
- type (string, required) -
SubscriberSpeedClassAttributeRule
orSimSpeedClassAttributeRule
- properties (object, required) - The settings for the rule.
- targetSpeedClass (string or
null
, optional) - Execute action(s) when the speed class is changed to this value. Valid options:null
or not set - Matches anytime a SIM or subscriber's speed class changes, regardless of the new speed class.s1.minimum
- Matches when a SIM or subscriber's speed class changes to s1.minimum.s1.slow
- Matches when a SIM or subscriber's speed class changes to s1.slow.s1.standard
- Matches when a SIM or subscriber's speed class changes to s1.standard.s1.fast
- Matches when a SIM or subscriber's speed class changes to s1.fast.s1.4xfast
- Matches when a SIM or subscriber's speed class changes to s1.4xfast.s1.8xfast
- Matches when a SIM or subscriber's speed class changes to s1.8xfast.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
- runOnceAmongTarget (boolean, optional) - See Additional Rule Properties below.
- targetSpeedClass (string or
Execute actions when a subscriber has expired as a result of its Expiration settings:
- type (string, required) -
SubscriberExpiredRule
orSimExpiredRule
- properties (object, required) - The settings for the rule.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
- runOnceAmongTarget (boolean, optional) - See Additional Rule Properties below.
Execute actions when the IMEI of the device using a subscriber does not match the subscriber's IMEI Lock settings:
- type (string, required) -
SubscriberImeiMismatchedRule
orSimImeiMismatchedRule
- properties (object, required) - The settings for the rule.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
- runOnceAmongTarget (boolean, optional) - See Additional Rule Properties below.
Execute actions when the current monthly bill total exceeds a specific amount:
- type (string, required) -
MonthlyChargeRule
- properties (object, required) - The settings for the rule.
- limitTotalAmount (string, required) - Execute action(s) when the current monthly bill total exceeds this value.
- inactiveTimeoutDateConst (string, required) - See Additional Rule Properties below.
- inactiveTimeoutOffsetMinutes (string, optional) - See Additional Rule Properties below.
Additional Rule Properties
- inactiveTimeoutDateConst (string, required) - Controls how long the event handler should wait before it re-evaluates the rule. Valid options:
IMMEDIATELY
- Re-evaluate the rule immediately.BEGINNING_OF_NEXT_MONTH
- Re-evaluate the rule at the beginning of the next month.BEGINNING_OF_NEXT_DAY
- Re-evaluate the rule at the beginning of the next day (at 00:00 UTC).AFTER_ONE_DAY
- Re-evaluate the rule one day (24 hours) later.NEVER
- Do not re-evaluate.
- inactiveTimeoutOffsetMinutes (string, optional) - Adds an additional delay in minutes after inactiveTimeoutOffsetMinutes, before the event handler re-evaluates the rule.
- runOnceAmongTarget (boolean, optional) - When enabled, specifies that the event handler should run only one across all SIMs or subscribers in the target, rather than for each SIM or subscriber individually, until the event handler is scheduled to re-evaluate. This parameter has no effect for Subscriber targets.
Action Parameters
Each event handler's actionConfigList parameter should be an array that consists of one or more actions, each of which follows one of the following action schemas.
Send an email:
- type (string, required) -
SendMailAction
orSendMailToOperatorAction
- properties (object, required) - The settings for the action.
- to (string, required) - The email address where the message will be sent (not required when using
SendMailToOperatorAction
). - title (string, required) - The email subject.
- message (string, required) - The email body.
- executionDateTimeConst (string, required) - See Additional Action Properties below.
- executionOffsetMinutes (string, optional) - See Additional Action Properties below.
- to (string, required) - The email address where the message will be sent (not required when using
Change a SIM or subscriber's status:
- type (string, required) - The status to change the SIM or subscriber to. Valid options:
ActivationAction
- Changes the SIM or subscriber's status to Active.DeactivationAction
- Changes the SIM or subscriber's status to Inactive.StandbyAction
- Changes the SIM or subscriber's status to Standby.SuspendAction
- Changes the SIM or subscriber's status to Suspended.
- properties (object, required) - The settings for the action.
- executionDateTimeConst (string, required) - See Additional Action Properties below.
- executionOffsetMinutes (string, optional) - See Additional Action Properties below.
Change a SIM or subscriber's speed class:
- type (string, required) -
ChangeSpeedClassAction
- properties (object, required) - The settings for the action.
- speedClass (string, required) - Change the subscriber's speed class to the specified speed class. Possible values:
"s1.minimum"
- Changes the subscriber's speed class to s1.minimum."s1.slow"
- Changes the subscriber's speed class to s1.slow."s1.standard"
- Changes the subscriber's speed class to s1.standard."s1.fast"
- Changes the subscriber's speed class to s1.fast."s1.4xfast"
- Changes the subscriber's speed class to s1.4xfast."s1.8xfast"
- Changes the subscriber's speed class to s1.4xfast.
- executionDateTimeConst (string, required) - See Additional Action Properties below.
- executionOffsetMinutes (string, optional) - See Additional Action Properties below.
- speedClass (string, required) - Change the subscriber's speed class to the specified speed class. Possible values:
Run a Webhook:
- type (string, required) -
ExecuteWebRequestAction
- properties (object, required) - The settings for the action.
- url (string, required) - The URL to execute, including any parameters.
- httpMethod (string, required) - The type of HTTP request. Possible values:
GET
,POST
,PUT
, orDELETE
. - contentType (string, required) - The HTTP request content type such as
application/json
. - headers (hash, optional) - The HTTP request header values. This value should be a string containing an escaped JSON object, with each key-value pair representing the HTTP request header name and header value, such as
"{\"x-header-name\": \"header-value\"}"
. - body (string, optional) - A character string to be set in the body of the request. Only used when httpMethod is set to
POST
orPUT
. - executionDateTimeConst (string, required) - See Additional Action Properties below.
- executionOffsetMinutes (string, optional) - See Additional Action Properties below.
Invoke an AWS Lambda Function:
- type (string, required) -
InvokeAWSLambdaAction
- properties (object, required) - The settings for the action.
- endpoint (string, required) - AWS Lambda function endpoint URL.
- functionName (string, required) - AWS Lambda function name (optional version number or function alias can also be set).
- accessKey (string, required) - AWS Lambda access key.
- secretAccessKey (string, required) - AWS Lambda secret access key.
- parameter1 (string, optional) - Optional parameter.
- parameter2 (string, optional) - Optional parameter.
- parameter3 (string, optional) - Optional parameter.
- parameter4 (string, optional) - Optional parameter.
- parameter5 (string, optional) - Optional parameter.
- executionDateTimeConst (string, required) - See Additional Action Properties below.
- executionOffsetMinutes (string, optional) - See Additional Action Properties below.
When the InvokeAWSLambdaAction action is executed, the following JSON is passed to the Lambda function:
{
"imsi": "295050012345678",
"parameter1": "my parameter 1",
"parameter2": "my parameter 2",
"parameter3": "my parameter 3",
"parameter4": "my parameter 4",
"parameter5": "my parameter 5"
}
The values can be accessed in the Lambda function as properties of the event
parameter:
exports.handler = function(event, context) {
console.log('Function called from IMSI ', event.imsi);
console.log('The value of parameter1 is ', event.parameter1);
context.succeed(event.imsi);
};
Variables
The SendMailAction
, SendMailToOperatorAction
, ExecuteWebRequestAction
, and InvokeAWSLambdaAction
actions allow you to define custom values or parameters that will be used in the email, webhook, or Lambda function.
See Variables above for the list of available variables.
Additional Action Properties
- executionDateTimeConst (string, required) - Controls how long the event handler should wait before it performs the action. Valid options:
IMMEDIATELY
- Execute the action immediately.BEGINNING_OF_NEXT_MONTH
- Execute the action at the beginning of the next month.BEGINNING_OF_NEXT_DAY
- Execute the action at the beginning of the next day (at 00:00 UTC).AFTER_ONE_DAY
- Execute the action one day (24 hours) later.NEVER
- Do not execute.
- executionOffsetMinutes (string, optional) - Adds an additional delay in minutes after executionDateTimeConst, before the event handler performs the action.
Once your event handler JSON configuration is ready, you can pass it into the Soracom API or Soracom CLI.
Soracom API
To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.
Then, use the createEventHandler API to create a new event handler:
curl -X POST \
> -H 'X-Soracom-API-Key: <MY-API-KEY>' \
> -H 'X-Soracom-Token: <MY-TOKEN>' \
> -H 'Content-Type: application/json' \
> -d '{
> "name": "...",
> "targetGroupId": "abcdef00-0000-0000-0000-000012345678",
> "ruleConfig": { ... },
> "actionConfigList": [ ... ],
> "status": "active"
> }' \
> https://g.api.soracom.io/v1/event_handlers
To edit an existing event handler, use the updateEventHandler API.
To delete an event handler, use the deleteEventHandler API.
Soracom CLI
To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.
Then, run the following command to create an event handler:
Here, the JSON array from the API example above should be passed in to the --body
parameter.
To edit an existing event handler, use the soracom event-handlers update
command.
To delete an event handler, use the soracom event-handlers delete
command.
Examples
Setting an Operator-Level Data Cap
This Event Handler configuration will set any SIM in your account that exceeds 25MB of data in a month to Inactive status, send an email to the specified address identifying the SIM that has exceeded the limit, and reactivate any SIM cards deactivated this way at the start of the next month.
{
"targetOperatorId": "OP0012345678",
"name": "25MB-Cap",
"description": "Deactivate until next month when 25MB is used",
"ruleConfig": {
"type": "SimMonthlyTotalTrafficRule",
"properties": {
"inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_MONTH",
"limitTotalTrafficMegaByte": "25"
}
},
"actionConfigList": [
{
"type": "DeactivationAction",
"properties": {
"executionDateTimeConst": "IMMEDIATELY"
}
},
{
"type": "SendMailAction",
"properties": {
"executionDateTimeConst": "IMMEDIATELY",
"to": "sora@soracom.io",
"title": "${simId} Has Exceeded the Data Usage Threshold",
"message": "${simId} has exceeded the 25 MB monthly data usage threshold configured in your account. It has been deactivated and will be automatically reactivated at the start of next month."
}
},
{
"type": "ActivationAction",
"properties": {
"executionDateTimeConst": "BEGINNING_OF_NEXT_MONTH"
}
}
],
"status": "active"
}
Explanation:
- This event handler will apply to all SIMs that belong to targetOperatorId
OP0012345678
. - It uses the SimMonthlyTotalTrafficRule rule, with the limitTotalTrafficMegaByte parameter set to
25
, which will cause the rule to execute when the SIM exceeds 25MB of data usage in a month. - The rule interval inactiveTimeoutDateConst is set to
BEGINNING_OF_NEXT_MONTH
, meaning that the event handler will execute the actions once when the rule conditions are met, and then will wait until the start of the next month before checking the SIM that triggered it again. - The event handler contains three actions:
- DeactivationAction which will
IMMEDIATELY
change the SIM status toInactive
. - SendMailAction which will
IMMEDIATELY
send an email notification informing a user of the deactivation. - ActivationAction which will set the SIM status to
Active
at theBEGINNING_OF_NEXT_MONTH
.
- DeactivationAction which will
Slack Notification
This Event Handler configuration will send a message to a Slack channel using Slack's incoming webhooks API when a SIM's Speed Class is changed.
{
"targetOperatorId": "OP0012345678",
"name": "SpeedClass-Slack",
"description": "Send a notification to Slack when a Speed Class changes",
"ruleConfig": {
"type": "SimSpeedClassAttributeRule",
"properties": {
"inactiveTimeoutDateConst": "IMMEDIATELY"
}
},
"actionConfigList": [
{
"type": "ExecuteWebRequestAction",
"properties": {
"executionDateTimeConst": "IMMEDIATELY",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"httpMethod": "POST",
"contentType": "application/json",
"body": "{\"text\":\"${imsi} speed class changed from ${oldSpeedClass} to ${newSpeedClass}!\"}"
}
}
],
"status": "active"
}
Explanation:
- This event handler will apply to all subscribers that belong to targetOperatorId
OP0012345678
. - It uses the SimSpeedClassAttributeRule rule, and omits the targetSpeedClass parameter, which means the rule will match all speed class changes.
- The rule interval inactiveTimeoutDateConst is set to
IMMEDIATELY
, meaning that once the rule conditions are met, the rule will be effective again with no delay. - The event handler contains one action:
- ExecuteWebRequestAction, which is configured
IMMEDIATELY
send aPOST
request tohttps://hooks.slack.com/services/...
, with content typeapplication/json
, and custom body content which includes variables${imsi}
,${oldSpeedClass}
, and${newSpeedClass}
.
- ExecuteWebRequestAction, which is configured
Downgrade Speed for One Day
This event handler configuration will execute a series of actions when a specific subscriber exceeds 100MB of data usage.
{
"targetImsi": "295050012345678",
"name": "100MB-Limit",
"description": "Slow down for 1 day and notify when 100MB is used",
"ruleConfig": {
"type": "SubscriberDailyTrafficRule",
"properties": {
"inactiveTimeoutDateConst": "AFTER_ONE_DAY",
"limitTotalTrafficMegaByte": 100
}
},
"actionConfigList": [
{
"type": "ChangeSpeedClassAction",
"properties": {
"executionDateTimeConst": "IMMEDIATELY",
"speedClass": "s1.slow"
}
},
{
"type": "SendMailAction",
"properties": {
"executionDateTimeConst": "IMMEDIATELY",
"to": "sora@soracom.io",
"title": "High Data Usage",
"message": "This device has reached 100MB in daily data usage, so its speed will be limited for one day.",
}
},
{
"type": "ChangeSpeedClassAction",
"properties": {
"executionDateTimeConst": "AFTER_ONE_DAY",
"speedClass": "s1.fast"
}
},
{
"type": "SendMailAction",
"properties": {
"executionDateTimeConst": "AFTER_ONE_DAY",
"to": "sora@soracom.io",
"title": "Device speed limit removed",
"message": "This device's speed limit has been removed.",
}
}
],
"status": "active"
}
Explanation:
- This event handler applies to an individual subscriber with targetImsi
295000012345678
. - It uses the SubscriberDailyTrafficRule rule, with the limitTotalTrafficMegaByte parameter set to
100
, which will cause the rule to execute when the subscriber exceeds 100MB of data usage. - The rule interval inactiveTimeoutDateConst is set to
AFTER_ONE_DAY
, meaning that the event handler will execute the actions once when the rule conditions are met, and then will wait one day before checking again. - The event handler contains four actions:
- ChangeSpeedClassAction, which will
IMMEDIATELY
change the speed class tos1.slow
. - SendMailAction, which will
IMMEDIATELY
send an email notification informing a user of the speed change. - ChangeSpeedClassAction, which will reset the speed class to
s1.fast
AFTER_ONE_DAY
passes. - SendMailAction, which will send another email notification
AFTER_ONE_DAY
informing the user that the speed limit has been removed.
- ChangeSpeedClassAction, which will
Invoke Lambda on Active Status
This event handler configuration will invoke an AWS Lambda function whenever a SIM's status changes to Active.
{
"targetOperatorId": "OP0012345678",
"name": "Status-Lambda",
"description": "Invoke Lambda function when a SIM is activated",
"ruleConfig": {
"type": "SimStatusAttributeRule",
"properties": {
"inactiveTimeoutDateConst": "IMMEDIATELY",
"targetStatus": "active"
}
},
"actionConfigList": [
{
"type": "InvokeAWSLambdaAction",
"properties": {
"executionDateTimeConst": "IMMEDIATELY",
"endpoint": "https://lambda.us-east-2.amazonaws.com",
"functionName": "my-lambda-function",
"accessKey": "ABC123XXXXXXXXXX",
"secretAccessKey": "ABC123XXXXXXXXXX",
"parameter1": "${oldStatus}",
"parameter2": "${newStatus}"
},
}
],
"status": "active"
}
Explanation:
- This event handler will apply to all subscribers that belong to targetOperatorId
OP0012345678
. - It uses the SimStatusAttributeRule rule, with the targetStatus parameter set to
"active"
, which will cause the rule to execute when any SIM is activated (status is changed to Active). - The rule interval inactiveTimeoutDateConst is set to
IMMEDIATELY
, meaning that once the rule conditions are met, the rule will be effective again with no delay. - The event handler contains one action:
- InvokeAWSLambdaAction, which is configured to
IMMEDIATELY
invoke themy-lambda-function
function athttps://lambda.ap-northeast-1.amazonaws.com
using the provided access key, pass the SIM's previous and current statuses to the Lambda function in the properties parameter1 and parameter2 respectively.
- InvokeAWSLambdaAction, which is configured to