Feature-Wallet Balance Alert

The Feature Wallet Balance Alert system enables real-time monitoring of wallet balances for specific features and triggers automated notifications when configured thresholds are breached. This powerful monitoring tool helps prevent service interruptions, manage usage limits, and track spending across your feature offerings.

Overview

Feature Wallet Balance Alerts provide a flexible, multi-level alerting system that monitors wallet balances associated with specific features. When a wallet balance crosses defined thresholds, the system automatically triggers alerts and sends webhook notifications, allowing you to take proactive action before critical issues arise. Key Benefits:

Prevent Service Interruptions: Get notified before wallet balance reaches critical levels
Multi-Level Alerting: Configure up to three independent alert levels (Critical, Warning, Info)
Real-Time Monitoring: Instant notifications via webhooks when thresholds are breached
Flexible Configuration: Set thresholds for “above” or “below” conditions based on your use case
Automated Tracking: No manual checking required—continuous background monitoring

Alert Levels

The system supports three independent alert levels, each with its own priority and purpose:

1. Critical (In Alarm) - Highest Priority

When to Use: When immediate action is required to prevent service disruption or critical issues. Example: Balance reaches $0 or less, meaning service may be interrupted within hours.

2. Warning - Medium Priority

When to Use: When attention is needed soon, but there’s still time to take action. Example: Balance reaches $10 or less, indicating low balance that needs replenishment soon.

3. Info - Lowest Priority

When to Use: For informational tracking and usage milestones. Example: Balance reaches $20 or less, serving as an early tracking indicator.

4. OK - No Alert

Example: Balance is healthy and above all configured thresholds.

Alert States

The system evaluates wallet balance against configured thresholds and determines the current alert state:

OK: Balance is healthy, no action needed
Info: Balance crossed info threshold, informational tracking only
Warning: Balance crossed warning threshold, attention needed
In Alarm: Balance crossed critical threshold, immediate action required

How It Works

Threshold Configuration

Each threshold consists of two components:

Threshold Value: The numeric value to monitor (e.g., 100.00)
Condition: The direction that triggers an alert
- “below”: Alert when balance is less than or equal to (≤) the threshold
- “above”: Alert when balance is greater than or equal to (≥) the threshold

Important: Alerts trigger on equality, not just when crossing the threshold. For example, if your critical threshold is set to $0 with “below” condition, the alert triggers when balance is exactly $0 or negative.

Threshold Ordering Rules

The system enforces proper ordering of thresholds based on the condition: For “below” condition (monitoring real-time ongoing-balance depletion):

Critical < Warning < Info

Example: Critical: $0, Warning: $10, Info: $20 For “above” condition (monitoring usage/spending):

Critical > Warning > Info

Example: Critical: $1000, Warning: $500, Info: $100

Configuration Flexibility

The system supports multiple configuration patterns:

Critical Only: Critical threshold without warning or info
Critical + Warning: Critical and warning thresholds without info
Critical + Info: Critical and info thresholds without warning
Info Only: Standalone info threshold without critical or warning
Full Stack: All three thresholds (critical, warning, and info)

Warning threshold requires a critical threshold. You cannot configure a warning threshold without also configuring a critical threshold.

Real-World Use Cases

Use Case 1: Prepaid Wallet Balance Monitoring

Scenario: Track prepaid wallet balance to prevent service interruption Configuration:

{
  "critical": {
    "threshold": "0.00",
    "condition": "below"
  },
  "warning": {
    "threshold": "10.00",
    "condition": "below"
  },
  "info": {
    "threshold": "20.00",
    "condition": "below"
  },
  "alert_enabled": true
}

How it works: Customer has a prepaid wallet starting with $100. As balance depletes:

Balance reaches $20 or less → Info alert (informational milestone, balance getting low)
Balance reaches $10 or less → Warning alert (low balance, needs top-up soon)
Balance reaches $0 or less → Critical alert (urgent, service will be interrupted)

Use Case 2: Monthly Spending Limit Monitoring

Scenario: Monitor spending against monthly spending limit Configuration:

{
  "info": {
    "threshold": "100.00",
    "condition": "above"
  },
  "warning": {
    "threshold": "500.00",
    "condition": "above"
  },
  "critical": {
    "threshold": "1000.00",
    "condition": "above"
  },
  "alert_enabled": true
}

How it works: Monthly spending limit of $1,000 set. As spending increases:

Spending reaches $100 or more → Info alert (spending milestone reached)
Spending reaches $500 or more → Warning alert (halfway to spending limit)
Spending reaches $1,000 or more → Critical alert (spending limit reached, action required)

Configuring Alerts via Dashboard

Follow these steps to configure feature wallet balance alerts:

Step 1: Navigate to Features

In the main navigation menu, select Features from Product Catalogue
Locate and select the feature you want to configure alerts for from the features list

Step 2: Access Alert Settings

In the feature details page, click the three-dot menu (⋮) in the top right corner
Select Alert Settings from the dropdown menu

Step 3: Configure Alert Thresholds

A dialog box titled “Feature Alert Settings” will appear with the following configuration options:

Configuration Options

Enable Alerts

Toggle the switch to activate balance monitoring for this feature
When disabled, no alerts will be triggered regardless of threshold settings

Alert Condition

Below: Alert when balance is less than or equal to (≤) the threshold (for monitoring balance depletion)
Above: Alert when balance is greater than or equal to (≥) the threshold (for monitoring spending/usage)

Critical Threshold (Required when Warning is set)

Enter the balance amount that triggers a critical alert
This is the highest priority alert level
Example for “below”: $0 (service will be interrupted)
Example for “above”: $1000 (spending limit reached)

Warning Threshold (Optional, requires Critical)

Enter the balance amount that triggers a warning alert
Medium priority alert level
Example for “below”: $10 (low balance, needs attention)
Example for “above”: $500 (approaching spending limit)

Info Threshold (Optional, can be standalone)

Enter the balance amount that triggers an info alert
Lowest priority alert level, informational only
Example for “below”: $20 (early warning indicator)
Example for “above”: $100 (usage milestone)

Save Changes

Click to apply the alert configuration
Alerts will begin monitoring immediately after saving

Cancel

Click to discard changes and close the dialog

Step 4: Verify Alert Configuration

After saving:

The feature will display an alert indicator showing alerts are enabled
Webhook notifications will be sent when thresholds are breached
You can view alert history in the feature’s activity log

State Transitions

The alert system evaluates balance changes and transitions between states automatically:

State Transition Examples

Scenario 1: Balance decreasing from $50 (below condition) Starting balance: $50 (above all thresholds)

Balance reaches $20 or less → OK → Info
Balance reaches $10 or less → Info → Warning
Balance reaches $0 or less → Warning → In Alarm
Balance increases to $50 (top-up) → In Alarm → OK

Scenario 2: Rapid balance decrease (below condition) Starting balance: $100 (above all thresholds)

Large transaction: Balance reaches $5 or less → OK → Warning (skips info, as $5 is ≤ $10 but > $0)
Another transaction: Balance reaches -$2 → Warning → In Alarm (balance is ≤ $0)

Scenario 3: Usage increase (above condition) Starting balance/usage: $0 (below all thresholds)

Usage reaches $100 or more → OK → Info
Usage reaches $500 or more → Info → Warning
Usage reaches $1000 or more → Warning → In Alarm
New billing cycle resets usage to $0 → In Alarm → OK

State transitions are unidirectional based on threshold crossings. The system never transitions “backwards” (e.g., Warning → Info) unless the balance crosses back over the threshold.

Webhook Integration

Webhook Event Type

When an alert threshold is breached, the system sends a webhook with the following event type:

feature.wallet_balance.alert

Webhook Payload Structure

{
  "alert_status": "in_alarm",
  "alert_type": "feature_wallet_balance",
  "event_type": "feature.wallet_balance.alert",
  "feature": {
    "id": "feat_01K8DBMBN87CY36DEFY62PEXBT",
    "name": "Alert Feat 1",
    "type": "metered",
    "alert_settings": {
      "alert_enabled": true,
      "critical": {
        "condition": "below",
        "threshold": "-15"
      },
      "warning": {
        "condition": "below",
        "threshold": "-5"
      },
      "info": {
        "condition": "below",
        "threshold": "0"
      }
    },
    "status": "published",
    "meter_id": "meter_01K8DBMBN5NRFNYBMXN1G3WDWY",
    "created_at": "2025-10-25T09:36:40.616655Z",
    "updated_at": "2025-10-25T11:14:15.925198Z"
  },
  "wallet": {
    "id": "wallet_01K8DC3ZAH6R55GTPFTWSR2EHF",
    "name": "Prepaid Wallet",
    "wallet_type": "PRE_PAID",
    "balance": "10",
    "credit_balance": "10",
    "currency": "usd",
    "alert_enabled": true,
    "alert_state": "in_alarm",
    "wallet_status": "active",
    "customer_id": "cust_01K8DBYJ0ST5GD57EB6EATEACE",
    "created_at": "2025-10-25T09:45:12.273036Z",
    "updated_at": "2025-10-25T09:58:22.259833Z"
  }
}

Webhook Fields Explained

Field	Description
`alert_status`	Current alert state: `ok`, `info`, `warning`, or `in_alarm`
`alert_type`	Type of alert: `feature_wallet_balance`
`event_type`	Webhook event identifier: `feature.wallet_balance.alert`
`feature.id`	Unique identifier of the feature
`feature.name`	Name of the feature being monitored
`feature.alert_settings`	Complete alert configuration including all thresholds
`wallet.id`	Unique identifier of the wallet
`wallet.balance`	Current wallet balance (total balance)
`wallet.credit_balance`	Current credit balance
`wallet.alert_state`	Current alert state of the wallet
`wallet.currency`	Currency of the wallet

Webhook Behavior

All alert states trigger webhooks: Info, Warning, and Critical all send notifications
Immediate delivery: Webhooks are sent instantly when state transitions occur
Retry logic: Failed webhook deliveries are automatically retried (up to 3 attempts)
Rate limiting: Webhook delivery is rate-limited to prevent spam (10 webhooks/second max)

Monitoring Implementation

The system uses two complementary monitoring approaches:

1. Real-Time Monitoring

Trigger: Wallet transactions (credit/debit operations)
Behavior: Immediate state evaluation on balance changes
Notifications: Instant webhook delivery
Use case: Primary monitoring mechanism for active wallets

2. Cron-Based Monitoring

Frequency: Every 5 minutes
Behavior: Periodic balance checks across all feature wallets
Purpose: Catches edge cases and ensures no alert is missed
Use case: Backup monitoring for reliability

Validation Rules

When configuring alerts, the system enforces the following validation rules:

Required FieldsWhen alert_enabled is true, at least one threshold (critical, warning, or info) must be provided.

Validation Error Examples

Error 1: Warning without Critical

{
  "warning": {
    "threshold": "10.00",
    "condition": "below"
  },
  "alert_enabled": true
}

❌ Error: “critical threshold is required when warning threshold is provided” Error 2: Incorrect Threshold Ordering

{
  "critical": {
    "threshold": "20.00",
    "condition": "below"
  },
  "warning": {
    "threshold": "10.00",
    "condition": "below"
  },
  "info": {
    "threshold": "0.00",
    "condition": "below"
  },
  "alert_enabled": true
}

❌ Error: “info threshold must be greater than warning threshold for ‘below’ condition” Error 3: No Thresholds Provided

{
  "alert_enabled": true
}

❌ Error: “at least one threshold (critical, warning, or info) is required when alert_enabled is true”

Best Practices

Set Critical Thresholds at Service Interruption PointsConfigure critical thresholds at the exact point where service would be interrupted or severely degraded.

Use 2-5x Multiplier for Warning ThresholdsSet warning thresholds at 2-5 times the critical threshold to provide adequate warning time.

Use 5-10x Multiplier for Info ThresholdsSet info thresholds at 5-10 times the critical threshold for early tracking indicators.

Test Alert Thresholds in StagingAlways test alert configurations in a staging environment before deploying to production.

Document Threshold DecisionsDocument why each threshold value was chosen for future reference and optimization.

Use “below” for Credit DepletionUse the “below” condition when monitoring balance depletion or credit consumption.

Use “above” for Usage LimitsUse the “above” condition when monitoring spending, usage limits, or consumption milestones.

Troubleshooting

Alerts Not Triggering

Possible causes:

alert_enabled is set to false
Threshold configuration is incorrect
Balance has not crossed the configured threshold
Webhook endpoint is not configured

Solution:

Verify alert_enabled is true
Check threshold values and conditions
Review current wallet balance
Confirm webhook endpoint is configured correctly

Wrong Alert State

Possible causes:

Threshold ordering is incorrect for the condition
Multiple thresholds using different conditions
Balance calculation is incorrect

Solution:

Verify threshold ordering matches condition (below: ascending, above: descending)
Ensure all thresholds use the same condition
Check wallet balance calculation logic

Summary

Feature Wallet Balance Alerts provide a comprehensive, flexible monitoring solution for tracking wallet balances across your feature offerings. Key takeaways:

Three independent alert levels: Critical, Warning, and Info
Flexible configurations: Standalone info, critical+info, or full stack
Real-time monitoring: Instant webhook notifications on threshold breaches
Multiple monitoring approaches: Real-time transaction monitoring + cron-based backup
Comprehensive error handling: Robust validation and error messages
Production-ready: Extensive logging, retry logic, and rate limiting

By implementing Feature Wallet Balance Alerts, you can proactively monitor usage, prevent service interruptions, and maintain a superior customer experience.

Introduction

Getting Started

Event Ingestion

Product Catalogue

Customers

Subscriptions

Wallet

Invoices

Webhooks

Settings

Data Exports

​Overview

​Alert Levels

​1. Critical (In Alarm) - Highest Priority

​2. Warning - Medium Priority

​3. Info - Lowest Priority

​4. OK - No Alert

​Alert States

​How It Works

​Threshold Configuration

​Threshold Ordering Rules

​Configuration Flexibility

​Real-World Use Cases

​Use Case 1: Prepaid Wallet Balance Monitoring

​Use Case 2: Monthly Spending Limit Monitoring

​Configuring Alerts via Dashboard

​Step 1: Navigate to Features

​Step 2: Access Alert Settings

​Step 3: Configure Alert Thresholds

​Configuration Options

​Step 4: Verify Alert Configuration

​State Transitions

​State Transition Examples

​Webhook Integration

​Webhook Event Type

​Webhook Payload Structure

​Webhook Fields Explained

​Webhook Behavior

​Monitoring Implementation

​1. Real-Time Monitoring

​2. Cron-Based Monitoring

​Validation Rules

​Validation Error Examples

​Best Practices

​Troubleshooting

​Alerts Not Triggering

​Wrong Alert State

​Summary

Overview

Alert Levels

1. Critical (In Alarm) - Highest Priority

2. Warning - Medium Priority

3. Info - Lowest Priority

4. OK - No Alert

Alert States

How It Works

Threshold Configuration

Threshold Ordering Rules

Configuration Flexibility

Real-World Use Cases

Use Case 1: Prepaid Wallet Balance Monitoring

Use Case 2: Monthly Spending Limit Monitoring

Configuring Alerts via Dashboard

Step 1: Navigate to Features

Step 2: Access Alert Settings

Step 3: Configure Alert Thresholds

Configuration Options

Step 4: Verify Alert Configuration

State Transitions

State Transition Examples

Webhook Integration

Webhook Event Type

Webhook Payload Structure

Webhook Fields Explained

Webhook Behavior

Monitoring Implementation

1. Real-Time Monitoring

2. Cron-Based Monitoring

Validation Rules

Validation Error Examples

Best Practices

Troubleshooting

Alerts Not Triggering

Wrong Alert State

Summary