Event Handler

Updated Configuration

The Event Handler Target and Rule settings can now be configured to apply to SIMs as well as Subscribers. This allows you to use the Event Handler with plan01s Subscription Containers. When an Event Handler is configured to target SIMs, the rule will apply to all subscriptions within each SIM, such as to check the total data used by the SIM, no matter which subscription is consuming data.

You can also configure Event Handlers to target Subscribers, which will apply a rule to only the primary plan01s subscription, and not to any subscription containers within the same SIM.

For most use cases, we recommend using the SIM-based rules, as these rules will allow you to add Subscription Containers in the future without changing any Event Handler settings.

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:

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

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.

Note: The Subscriber target does not apply to planP1 or planX1 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.

Note: The Subscriber rules do not apply to planP1 or planX1 subscription containers. If you want to use rule that targets a subscription container, use one of the rules below instead.

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 supress 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.

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.

When using the Subscriber status attribute, Sim status attribute, Subscriber expired, or Sim expired rules, you can also use these variables in the actions:

Similarly, when using the Subscriber speed class attribute or Sim speed class attribute rules, you can use these variables in the actions:

The Sim subscription status rule contains additional variables useful for checking the Subscription Container status:

Variables can be used in the following action parameters:


Creating an Event Handler

  1. Login to the User Console. From the Menu, open the Event Handler screen.

    https://console.soracom.io

    Create Event Handler

  2. Click the Create Event button.

  3. Enter the event handler configuration parameters:

    https://console.soracom.io

    Event Handler Configuration

    • 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.
  4. Click the Create button.

Editing an Event Handler

  1. Login to the User Console. From the Menu, open the Event Handler screen.

  2. From the list of event handlers, click the name of the event handler that you want to edit.

    https://console.soracom.io

    Edit Event Handler

  3. Enter the event handler configuration parameters.

  4. Click the Update button.

Deleting an Event Handler

  1. Login to the User Console. From the Menu, open the Event Handler screen.

  2. From the list of event handlers, click the for the event handler you want to delete, then click the Delete button.

    https://console.soracom.io

    Delete Event Handler

  3. Click the Delete button again to confirm.

    Delete Event Handler


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:

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.
    • SimDailyTrafficRule - Matches when a SIM's total daily data usage across all of its subscriptions exceeds a specified value.
    • SimMonthlyTrafficRule - Matches when a SIM's total monthly data usage across all of its subscriptions exceeds a specified value.
    • SimCumulativeTrafficRule - 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 or SimStatusAttributeRule
  • 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 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.
      • 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.

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.

Execute actions based on a SIM or subscriber's speed class (s1.minimum, s1.standard, etc.):

  • type (string, required) - SubscriberSpeedClassAttributeRule or SimSpeedClassAttributeRule
  • 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.
    • 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 a subscriber has expired as a result of its Expiration settings:

  • type (string, required) - SubscriberExpiredRule or SimExpiredRule
  • 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.
Additional Rule Properties

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 or SendMailToOperatorAction
  • 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.

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.
  • 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.
    • executionDateTimeConst (string, required) - See Additional Action Properties below.
    • executionOffsetMinutes (string, optional) - See Additional Action Properties below.

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, or DELETE.
    • 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 or PUT.
    • 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

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:

soracom event-handlers create --body "<CONFIG>" --coverage-type g

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

Slack Notification

This Event Hander 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:


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:


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: