Soracom Event Handler

Example Configurations

Disable SIMs that Use More than 25MB in a Month

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:
  1. DeactivationAction which will IMMEDIATELY change the SIM status to Inactive.
  2. SendMailAction which will IMMEDIATELY send an email notification informing a user of the deactivation.
  3. ActivationAction which will set the SIM status to Active at the BEGINNING_OF_NEXT_MONTH.

Send Slack Notifications on Speed Class Change

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:
  1. ExecuteWebRequestAction, which is configured IMMEDIATELY send a POST request to https://hooks.slack.com/services/..., with content type application/json, and custom body content which includes variables ${imsi}, ${oldSpeedClass}, and ${newSpeedClass}.

Downgrade Speed for One Day When 100MB Is Consumed

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 295050012345678.
• 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:
  1. ChangeSpeedClassAction, which will IMMEDIATELY change the speed class to s1.slow.
  2. SendMailAction, which will IMMEDIATELY send an email notification informing a user of the speed change.
  3. ChangeSpeedClassAction, which will reset the speed class to s1.fast AFTER_ONE_DAY passes.
  4. SendMailAction, which will send another email notification AFTER_ONE_DAY informing the user that the speed limit has been removed.

Invoke Lambda on Change to 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:
  1. InvokeAWSLambdaAction, which is configured to IMMEDIATELY invoke the my-lambda-function function at https://lambda.us-east-2.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.