Developer documentation

Configuring Totogi Notifications using AWS EventBridge

This document introduces Totogi customers and prospective developers to the concept of Totogi Notifications. First, these docs will explain what is required to receive notifications and how to set this up. Next, they’ll show which Notification event detail records (EDRs) or call detail records (CDRs) are triggered, when they are triggered and the structure, and information contained within the message received in your environment. Finally, in the three appendices of this document, there are a set of troubleshooting instructions and advanced configuration options.

Requirements

In order to begin working with Totogi Notifications, you will need to:

Creating your notifications EventBus

Totogi Notifications work by sending notification events to your Amazon EventBridge bus from Totogi. This means, we need the ARN number of your EventBridge EventBus to send the message to you. 

In your AWS account, you can create an EventBus that will receive all the notifications from Totogi either manually or with this CloudFormation template that we provide you:

Sign into the AWS account you want to use, then click the template button above to create a CloudFormation stack with all the EventBridge resources you need and an initial CloudWatch Logs integration to see events flowing through your provider. 

The CloudFormation template will create:

After the CloudFormation stack is deployed, sign in to Plan Design with your tenant’s Admin user.

Browse to the Network section, and open the EventBridge feature. Click the ‘Set up Event Bridge’ button, and provide the ARN number created by the Cloudformation script. 

Save the setting and your Event Bridge will be ready for use. You should be able to see any new events in the CloudWatch log group appear whenever you’re triggering new events. 

Acting on Notifications

Ultimately, you decide which notifications to process and how. You can use these events to send SMS messages to your subscribers, trigger promotional offers, send email reminders, and much more.

You can add any rules to send EventBridge events to any of the supported targets in the AWS Documentation.

Appendix C shows instructions for building a Totogi charging emulator demo app that can help you understand how to use Totogi Notifications.

Available Notifications

Totogi provides different notification types that allow you to take action on distinct system events. With these events, you can act on common lifecycle triggers like upcoming plan expiration or low balances to trigger your own event-driven workflows. Often, these include SMS reminders, email marketing campaigns, new retention offers and other high-value actions. 

Plan Expiry Warning: Triggered X <hours|days> before a Plan End Date as configured in the plan or general settings. Does not trigger when the expiry is for an upgrade to a new plan version or a plan that auto-renews

Plan Expired: Triggered when a non auto-renewable plan has expired.

Plan Canceled: Triggered when a Plan is removed from an account, however not triggered when it is upgraded to a new plan version

Plan Rollover: Triggered when any allowance is rolled over into a new period. The notification payload includes all data types and the quantity rolled over.

Service Provider Credit Limit: Triggered when  the value of the main currency balance is equal to a value set when the plan is provisioned to a subscriber. The default value is 0.

Account Credit Limit: Triggered when the value of the main currency balance is equal to a value set when the plan is provisioned to an account. 

This Credit Limit is for account self-care enforcement where they want to ensure their own spend does not exceed some budget. This can not be set to a value higher than the Service Provider Credit Limit.

Auto-renew Success: Triggered when a recurring plan successfully auto-renews and for pre-paid the renewal fee is deducted from the monetary balance.

Auto-renew Failure: Triggered when a recurring plan is unable to auto-renew. A renewal grace period can be configured in the plan and there is an auto-retry mechanism in place. The renewal will be attempted on each charging request until the grace period runs out. An auto-renew failure notification will be triggered each time a renewal is unsuccessful.

Allowance Threshold: Associated with any allowance balance (MB, text, min) and is intended to trigger a notification when the allowance falls below threshold.
Please note: In Plan Design the threshold is set as a percentage of the total balance.

New Plan Activated: Triggered when a new plan is successfully provisioned to a subscriber. In addition to the standard payload the Plan ID is also included.

Notification Structure

The base notification event includes the following fields

Field NameDescription
provideridIdentifying the provider.
invocationtimestampThis field holds the timestamp when the API invocation request is submitted to the charging function.
dayThe day of the month the notification was generated
monthThe month the notification was generated
yearThe year the notification ws generated
eventdataStructure containing the details of the notification information
accountidThe account for which the notification is raised
deviceid(optional) The device that triggered the notification
charginginformationStructure containing charging relevant information
chargingsessionidentifierSession Id in which context the notification was triggered
notificationInformationStructure containing notification information
nameNotification name (see Identifying Notifications on the EventBus)
stateCurrent state of the notification counter
prevstateLast state of the counter
thresholdThreshold value that triggered the state change
notificationfieldsStructure containing addition notification specific information (see Additional Information for Specific Notifications

Identifying Notifications on the EventBus

The following table maps the defined Notifications to the values used in the notification structure

NotificationNamestate
Plan Expiry WarningPlanExpiryWarning warning
Plan ExpiredPlanExpiredexpired
Plan CanceledPlanCancelledcancelled
Plan RolloverPlanRolloverrolloverOccured
Service Provider Credit LimitOutOfCreditoutOfCredit
Account Credit LimitAccountCreditWarningwarning
Auto-renew SuccessAutoRenewSuccessrenewSuccess
Auto-renew FailureAutoRenewFailurerenewFailure
Allowance ThresholdUnitAllowanceThresholdlow
New Plan ActivatedNewPlanActivatedactive

Additional Information for Specific Notifications

NotificationAdditional Notification FieldsDescription
Plan RolloverrolloveramountAmount rolled over 
rollovergraceperiodPeriod the roll over amount remain valid
New Plan ActivatedplanidPlanId of the Plan activated on the account.

Appendix A

Advance Configuration of the EventBus

If you’d like to remove the rule targeting CloudWatch or make any other changes, copy and modify this template.

At that point, you can also add new targets to the EventBus to help manage any custom workflows you want to support while processing these events.

Appendix B

Troubleshooting and Debugging EventBus Permissions

Depending on how you create the EventBus and how you configure Rules and targets you may need to set additional permissions if you want events to be shown in the CloudWatch logs group. Our template creates a log group under /aws/events/{logGroupName}, which is a supported location from the default EventBridge policy when you create the rule.

However, if you’re not seeing events after testing, make sure to check the resource policy on the log groups. You can do this via the AWS CLI:

aws logs describe-resource-policies

An easy way to view the policy that comes out more easily you can use jq:

aws logs describe-resource-policies --region us-east-1 | jq | jq '.resourcePolicies[0].policyDocument | fromjson'

Result:

{

  "Version": "2012-10-17",

  "Statement": [

    {

      "Sid": "TrustEventsToStoreLogEvent",

      "Effect": "Allow",

      "Principal": {

        "Service": [

          "delivery.logs.amazonaws.com",

          "events.amazonaws.com"

If those components of the policy are missing, you should use the Put Resource Policy command to add a new policy that includes permissions for EventBridge to add logs to the target resource:

{

"Version": "2012-10-17",

  "Statement": [

    {

      "Sid": "TrustEventsToStoreLogEvent",

      "Effect": "Allow",

      "Principal": {

        "Service": [

          "delivery.logs.amazonaws.com",

          "events.amazonaws.com"

        ]

      },

      "Action": [

        "logs:CreateLogStream",

        "logs:PutLogEvents"

      ],

      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/events/*:*"

    }

  ]

}

If you see events.amazonaws.com in the policy under the Principal section and the CreateLogStream and PutLogEvents actions as shown above – then your EventBridge should have permissions to publish events to CloudWatch.

Appendix C

Using Notifications in a charging emulator demo app

We’ve created a how-to guide with step-by-step instructions on how to build a Totogi charging emulator demo app (the tool we use to demonstrate some of the functionality of our charger across multiple demo tenants.) Use the charging emulator demo app to process low balance notifications and records them to be looked up based on tenant, account, and time.

The charging emulator demo app shows a Serverless Framework service that triggers a Lambda Function to review all EventBridge Events. Then, on certain events (such as low balance notifications), the demo app records the events and makes them accessible via an API. However, you could easily change this application for your own purposes by rewriting the handle_threshold function to take any action you’d like based on different event types.