#
wallet.balance_low
#
Introduction
The wallet.balance_low webhook is triggered when the merchant's wallet balance reaches or falls below their configured low balance threshold. This allows you to proactively alert merchants and help them maintain sufficient balance for uninterrupted service.
The merchant configures the warning balance level in their Business App dashboard:
For more details on webhook configuration, see the App Creation section.
#
Webhook Request
When the wallet balance reaches the low threshold, Armada sends a POST request to your configured webhook URL.
#
Payload Headers
These are the useful headers you need. The request may include additional headers, but these are the essential ones:
#
Payload Schema
{
"balance": Number, // Current wallet balance
"warning_balance_level": Number, // Configured low balance threshold
"currency": "String" // Currency code (KWD, BHD, SAR)
}
#
Payload Example
{
"balance": 20,
"warning_balance_level": 50,
"currency": "KWD"
}
#
Response Requirements
Your webhook endpoint must respond with a 200 status code to acknowledge receipt.
#
Best Practices
Identify the Merchant: Use x-armada-app-id and x-armada-installation-id headers together to identify which merchant installation has low balance.
Respond Quickly: Return 200 OK immediately upon receiving the webhook, then process the alert asynchronously.
Handle Idempotency: Use x-armada-webhook-id to track processed webhooks and avoid duplicate alerts.
#
Use Cases
Send email, SMS, or push notifications to merchants or finance teams when balance is running low.
Display prominent balance warnings in merchant dashboards to encourage timely top-ups.
Trigger payment processing or redirect merchants to payment pages when balance reaches threshold.
Track spending patterns and balance trends to optimize warning thresholds and predict top-up needs.