Introduction & Webhooks

Whenever a successful action happens on Celbux, it is funneled through the Notification Engine. This microservice allows integrators to execute automated HTTP callbacks (webhooks), as well as dispatch conditional SMS and Email notifications based on the exact event that occurred.

Events such as /createVoucher, /pay, and /withdraw can be hooked into, and dynamic variables for the event are delivered in real-time. These events are configured per community and are identified by a unique Transaction Type (TT).

Webhooks & Callbacks

The Notification Engine can send a standard HTTPS POST request with a JSON payload to an endpoint of your choosing. Custom headers can be specified within the community configuration (e.g., specific Authorization keys), and the engine will always automatically inject Content-Type: application/json.

Please note that each TT will populate different variables. If a variable is not applicable to a specific TT, it will be sent through as a zero-value (0 for integers/floats, and "" for strings).

Payload Variables

When the Notification Engine constructs a payload, it exposes a massive state of variables linked to the transaction. Below is a categorized, exhaustive list of all fields that will be generated in your JSON payload or SMS templates.

Note: Security fields (Misc_Password, and Misc_OTP) are completely excluded from webhook JSON payloads for security purposes, but they are accessible for standard SMS/Email messaging routing.

Action Variables

Context on the core action that triggered the Notification Engine.

Field	Type	Description
Action_Community	String	The community namespace where the action occurred.
Action_DisbursementUIDx	String	The unique ID of the disbursement batch (if applicable).
Action_ID	Integer	Internal Action ID.
Action_Namespace	String	Primary routing namespace.
Action_TT	Integer	The Transaction Type (TT) triggered.
Action_VoucherType	String	The general voucher type referenced during the action.

Voucher Variables

Details about the voucher currently being transacted.

Field	Type	Description
Voucher_Amount	Integer	Balance of the voucher in cents.
Voucher_AmountStr	String	Formatted balance string (e.g. R10.00).
Voucher_DisplayName	String	User-facing title for the voucher type community.
Voucher_No	String	Unique voucher number.
Voucher_Title	String	Fully formatted string representing the voucher.
Voucher_Type	String	String identifier of the voucher type.
Voucher_WithdrawFee	Integer	Fee charged to withdraw the voucher in cents.
Voucher_WithdrawFeeStr	String	Formatted withdrawal fee string.

Audit Variables

The core financial ledger values linked to this exact transaction.

Field	Type	Description
Audit_Amount	Integer	Transaction amount in cents.
Audit_AmountNet	Integer	The net amount after commissions/fees.
Audit_AmountNetStr	String	Formatted net amount string.
Audit_AmountStr	String	Formatted transaction amount string.
Audit_Comms	Integer	Total commission/fees charged.
Audit_CommsNet	Integer	Net commissions recorded.
Audit_CommsNetStr	String	Formatted net commissions string.
Audit_CommsStr	String	Formatted total commissions string.
Audit_FromBalance	Integer	The payer’s wallet/voucher balance after transaction.
Audit_FromBalanceStr	String	Formatted payer balance string.
Audit_FromCardPANNo	String	Associated PAN number of the payer (if a card transaction).
Audit_ID	Integer	Unique identifier for the audit record.
Audit_LastTransaction	Integer	Timestamp of the last transaction.
Audit_Metadata	String	Extracted JSON string containing transaction metadata.
Audit_NewUser	Integer	Indicates whether a new user was created (1) or not (0).
Audit_Overdraft	Integer	Overdraft utilization value in cents.
Audit_OverdraftStr	String	Formatted overdraft string.
Audit_Timestamp	Integer	Exact execution timestamp of the ledger entry.
Audit_ToBalance	Integer	The payee’s wallet/voucher balance after transaction.
Audit_ToBalanceStr	String	Formatted payee balance string.
Audit_ToCardPANNo	String	Associated PAN number of the payee (if a card transaction).
Audit_TrxID	String	Unique transaction ID reference.
Audit_TT	Integer	Audit-specific Transaction Type.
Audit_Type	String	Descriptive name of the transaction type (e.g., Buy, Withdraw).

User State (From_* & To_*)

Both From_ (the payer) and To_ (the payee) share identical data objects reflecting the user’s state on the platform. (Replace the prefix below with To_ to get the payee’s variables).

Field	Type	Description
From_AccountName	String	Bank account holder name.
From_AccountNumber	String	Bank account number.
From_AccountType	String	Bank account type (Savings, Cheque, etc).
From_Balance	Integer	Current user wallet balance in cents.
From_BalanceStr	String	Formatted user wallet balance.
From_BankName	String	User’s bank institution name.
From_BannerImageUrl	String	URL of the profile banner.
From_BranchCode	String	Bank branch code.
From_CanWithdraw	String	Indicator if user is authorized to withdraw.
From_CommercialRegistrationNumber	String	Commercial entity registration number.
From_Commission	Float	Base commission configuration percentage.
From_Currency	String	Default currency code (e.g. ZAR).
From_DepositComms	Float	Percentage taken on deposits.
From_DepositCommsMax	Integer	Maximum deposit commission in cents.
From_DepositCommsMaxStr	String	Formatted maximum deposit commission.
From_DepositCommsMin	Integer	Minimum deposit commission in cents.
From_DepositCommsMinStr	String	Formatted minimum deposit commission.
From_DepositFee	Integer	Flat fee applied to deposits.
From_DepositFeeStr	String	Formatted deposit fee.
From_DisplayName	String	Formatted display name for the user.
From_Email	String	Registered email address.
From_FirstName	String	User’s first name.
From_Group	String	Categorization group of the user.
From_HouseNumber	String	Physical address house number.
From_IDNumber	String	National ID or Passport number.
From_KYCStatus	String	Current KYC verification tier.
From_LastTransaction	Integer	Timestamp of user’s last ledger movement.
From_LastName	String	User’s last name.
From_Latitude	Float	Geo-location latitude.
From_Longitude	Float	Geo-location longitude.
From_LowBalanceAlertAmount	Integer	Threshold for sending low balance alerts.
From_LowBalanceAlertAmountStr	String	Formatted low balance threshold.
From_MSISDN	String	Cellphone number used for communications.
From_NotificationChannels	String	Preferred methods of contact (SMS, Email, etc).
From_Overdraft	Integer	Allowable overdraft limit.
From_OverdraftStr	String	Formatted overdraft limit.
From_ProfileImageUrl	String	URL of the user’s profile image.
From_Provider	String	Top-level provider organization name.
From_Province	String	Physical address province.
From_Status	String	Active status of the user profile.
From_StreetName	String	Physical address street name.
From_Suburb	String	Physical address suburb.
From_TaxNumber	String	Registered tax entity number.
From_Timezone	String	Local timezone (e.g., Africa/Johannesburg).
From_Town	String	Physical address town.
From_TransferCommission	Float	Commission applied to standard P2P transfers.
From_Type	String	Single letter user role (e.g., S, M).
From_UMetadata	String	Stringified metadata attached to the user.
From_UserID	Integer	Internal User ID.
From_Username	String	Unique system username.
From_UsernameHistory	String	Record of previous usernames linked to this account.
From_Verification	String	Verification status text (e.g., Verified).

Log Variables (Log_*)

Information gathered from the system’s request pipeline, tracking API origin, IPs, and context. (Shares many variables with User State, representing the executing user).

Field	Type	Description
Log_Action	String	Descriptive action being requested.
Log_Error	String	The exact error message thrown, if any.
Log_HostName	String	Origin host of the request.
Log_HostPort	String	Origin port of the request.
Log_ID	Integer	Unique identifier for the log entry.
Log_IPAddress	String	Origin IP address.
Log_Metadata	String	Request metadata string.
Log_Status	String	Response status text.
Log_StoreID	String	Requesting merchant’s StoreID.
Log_TID	String	Master Transaction ID of the request.
Log_Timestamp	Integer	Execution timestamp of the request.
Log_Username	String	Username of the executor.
Log_XForwarded	String	Raw X-Forwarded-For header string.
Log_XForwarded1	String	Parsed client IP from X-Forwarded-For.

Error Variables (Error_*)

Details of the exact failure point if the action failed.

Field	Type	Description
Error_Action	String	Action that triggered the error.
Error_Amount	Integer	Amount attempted.
Error_AmountStr	String	Formatted amount attempted.
Error_ID	Integer	Internal error log ID.
Error_Message	String	Human readable string detailing why the process failed.
Error_Metadata	String	Contextual metadata related to the error.
Error_Status	Integer	Status code associated with the error.
Error_Timestamp	Integer	Timestamp the error occurred.
Error_Treasury	String	Treasury/Community associated with the failed action.

Miscellaneous Variables (Misc_*)

Helper variables passed into templates (e.g., merged vouchers, one-time pins, balance alerts).

Field	Type	Description
Misc_ExpiryStr	String	String detailing when a token/OTP expires.
Misc_IsViralCreateUser	String	Indicates if the user was created virally without upfront registration.
Misc_LowBalanceAlertAmount	Integer	Alert threshold triggered in cents.
Misc_LowBalanceAlertAmountStr	String	Formatted alert threshold triggered.
Misc_NewMSISDN	String	The new MSISDN being migrated to.
Misc_OTP	String	Available for SMS/Email only. The requested One-Time PIN.
Misc_Password	String	Available for SMS/Email only. Generated password for viral user creation.
Misc_SettleVoucherAmount	Integer	Value of the newly settled/accumulated voucher in cents.
Misc_SettleVoucherAmountStr	String	Formatted value of the settled voucher.
Misc_SettleVoucherDisplayName	String	Display name of the settled voucher.
Misc_SettleVoucherNo	String	The new unique voucher number generated post-settlement.

Card PAN Variables

If the transaction interacted with physical/digital linked cards. Both FromCardPAN_ and ToCardPAN_ objects are available.

Field	Type	Description
FromCardPAN_AutoCreateVoucher	String	Indicator if card automatically handles voucher translation.
FromCardPAN_CardBalance	Integer	Card balance strictly linked to the PAN in cents.
FromCardPAN_CardBalanceStr	String	Formatted PAN balance.
FromCardPAN_CardStatus	String	Current active state of the card.
FromCardPAN_Community	String	Community the card is locked to.
FromCardPAN_DisplayName	String	Friendly display name for the card.
FromCardPAN_Owner	String	Username of the PAN owner.
FromCardPAN_Type	String	Voucher Type underlying the PAN limit.
FromCardPAN_UserBalance	Integer	Total user balance associated across limits.
FromCardPAN_UserBalanceStr	String	Formatted user PAN balance.
FromCardPAN_WithdrawFee	Integer	PAN-specific withdrawal fee.
FromCardPAN_WithdrawFeeStr	String	Formatted PAN withdrawal fee.

Example Webhook Payload

Here is an example of a webhook JSON body triggered by a TT4 (/pay transaction). Notice how the engine automatically formats Integers and Strings correctly.

{
    "Action_ID": 1593847,
    "Action_TT": 4,
    "Action_Community": "celbux101",
    "Action_VoucherType": "Cash",
    "Voucher_Title": "Voucher Cash ZAR 1025.00 Number : 168-04085-22492",
    "Voucher_No": "168-04085-22492",
    "Voucher_Type": "Cash",
    "Voucher_DisplayName": "Cash",
    "Voucher_Amount": 102500,
    "Voucher_AmountStr": "R1,025.00",
    "Voucher_WithdrawFee": 1000,
    "Voucher_WithdrawFeeStr": "R10.00",
    "Audit_ID": 99381,
    "Audit_LastTransaction": 1696792732118,
    "Audit_Timestamp": 1696792731370,
    "Audit_Metadata": "{\"Amount\":\"1000\",\"datetime\":\"2023/10/08 19:18\"}",
    "Audit_FromBalance": 101500,
    "Audit_FromBalanceStr": "R1,015.00",
    "Audit_ToBalance": 5045000400,
    "Audit_Amount": 1000,
    "Audit_AmountStr": "R10.00",
    "Audit_TrxID": "3026-3110-2554",
    "Audit_Type": "Buy",
    "Audit_TT": 4,
    "From_LastTransaction": 1696792732118,
    "From_Balance": 210026,
    "From_BalanceStr": "R2,100.26",
    "From_Currency": "ZAR",
    "From_Username": "27717583600",
    "From_MSISDN": "27648503047",
    "From_DisplayName": "Matthew Williams",
    "From_IDNumber": "9927541665757",
    "From_Email": "matthew.williams@example.com",
    "From_Type": "S",
    "From_Verification": "Verified",
    "To_LastTransaction": 1696796724108,
    "To_Balance": 5045000400,
    "To_BalanceStr": "R50,450,004.00",
    "To_Currency": "ZAR",
    "To_Username": "celbux",
    "To_MSISDN": "27717583600",
    "To_DisplayName": "John Mercantile",
    "To_IDNumber": "8927541895536",
    "To_Email": "john.mercantile@example.com",
    "To_Type": "M",
    "To_Verification": "Verified",
    "Log_ID": 78219,
    "Log_Timestamp": 1696796723218,
    "Log_Username": "celbux",
    "Log_Action": "Process Payment",
    "Log_Status": "Success"
}