Soracom Event Handler

Overview

The Event Handler feature is a service that allows you to build automations based on SIM events, such as 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.

Multiple event handlers can be configured for the same target. When a SIM meets the conditions of multiple event handler rules, all corresponding actions will be executed.

Limitations

• When the target of an event handler is set as a group, SIM and Subscriber-based rules will be evaluated for each individual SIM or subscriber belonging to the group, rather than to all SIMs or subscribers collectively.
• Data usage rules for daily and monthly limits are evaluated according to UTC (Coordinated Universal Time).
• 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.
• When using the Monthly bill amount rule, 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 configured in your rule, 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.
• When a rule targets a Group, if a SIM is removed from the group partway through the Event Handler’s daily or monthly period, any data usage prior to its removal will still be included in the group’s total. Conversely, if a SIM is added to the group during the period, any usage that occurred before it was added will not be counted.
• Each event handler is limited to a maximum of 5 actions.
• Rule evaluation timing is not guaranteed. Various factors can cause time delays in when rules are evaluated.
• Data usage rules cannot use "Immediately" for re-evaluation. When configuring rules based on data consumption (daily, monthly, or cumulative traffic), the Re-evaluate parameter cannot be set to Immediately. You must specify a different interval such as "Beginning of next day" or "Beginning of next month".
• Action execution timing is not guaranteed. Various factors can cause time delays in when actions are performed after a rule condition is met.
• Action content is determined when the rule condition is met. If you modify an event handler configuration after a rule has been triggered but before its actions are executed, the original configuration will be used for those pending actions.
• When multiple actions are configured with the same Run timing, their execution order is not guaranteed. Use the Run in offset parameter to control execution sequence. For example, to ensure Action A executes before Action B, set Action A's Run in to 0 minutes and Action B's Run in to 5 minutes.

Each Soracom account is limited to the following number of event handler configurations per target type:

For example, you can configure 10 event handlers targeting an operator and an additional 10 event handlers targeting a specific IMSI.