This documentation covers how to set up and validate Bold Bank webhooks. Webhooks allow you to receive real-time notifications about events in your Bold Bank account.

Webhooks are automated messages sent from Bold Bank to your application when specific events occur. This documentation explains how to set up webhooks, validate their authenticity, and handle incoming events.

​
Webhook Overview

​
How to Set Up Your Webhook URL

To set up your webhook URL, log in to your Bold Bank account and navigate to the settings page. Input the desired webhook URL in the appropriate field and confirm the change by entering your password for security. Once set, Bold Bank will start sending real-time notifications to the specified URL.

To get your API secret key and public key, simply click on “Generate” in the same section. For first-time users, a one-time public key and secret key will be generated. The secret key must be copied immediately, as subsequent attempts to generate it will change the key, although the public key will remain the same.

Webhooks are HTTP callbacks that notify your application of events such as successful transactions, failed payments, or account updates. When an event occurs, Bold Bank sends a POST request with a JSON payload to your specified webhook URL.

​
Webhook Structure

Each webhook payload contains the following fields:

  • event: The type of event that triggered the webhook (e.g., bankTransfer.success).
  • eventData: Detailed information about the event. This includes:
    • sessionId: A unique identifier for the transaction session.
    • productType: The type of product involved in the transaction (e.g., Fund Account, Bank Transfer).
    • amount: The total amount involved in the transaction.
    • netAmount: The amount after fees and commissions.
    • fee: The fee charged for the transaction.
    • commission: Any commission earned from the transaction.
    • transactionStatus: The status of the transaction (e.g., SUCCESS, FAILED).
    • transactionReference: A unique reference for the transaction.
    • customerReference: An optional reference provided by the customer.
    • comment: Any comments associated with the transaction.
    • createdAt: The timestamp when the transaction was created.
    • transactionAccount: The account involved in the transaction.
    • transactionType: Indicates whether the transaction is a CREDIT or DEBIT.
    • Additional fields specific to the event type (e.g.,beneficiary details).
  • signature: A cryptographic signature to verify the authenticity of the webhook.
{
"event": "fundAccount.success",
"eventData": {
  "sessionId": "103000250304182805630178659659",
  "productType": "Fund Account",
  "amount": "8888.00",
  "netAmount": "8888.00",
  "fee": "0.00",
  "commission": "20.00",
  "transactionStatus": "SUCCESS",
  "transactionReference": "663A33CA453D3B109286",
  "customerReference": null,
  "comment": "Sandbox payin simulation",
  "createdAt": "2025-03-04T18:28:06.000000Z",
  "transactionAccount": "8160000000",
  "transactionType": "CREDIT",
  "sender": {
    "accountName": "Yusuf Yusuf Agboola",
    "accountNumber": "9011724470",
    "bankName": "SHEPHERD TRUST MICROFINANCE BANK",
    "bankCode": "090401",
    "stampDuty": "0.00"
  }
},
"signature": "75c26b7e148442184761da0183c400984382c9b61383d24ce2161137da122658"
}

While the webhook payload will contain a variety of fields describing the event, it is important to always check the transactionStatus within eventData to determine the true status of the transaction. This field reflects whether the transaction has been successfully processed, failed, or is pending.

​
Signature Validation

To ensure the authenticity of incoming webhooks, Bold Bank includes a cryptographic signature in each payload. You must validate this signature to confirm that the webhook originated from Bold Bank.

​
How to Validate the Signature

The signature is generated using the HMAC-SHA256 algorithm. To validate it:

  1. Convert the payload (excluding the signature field) to a JSON string.
  2. Hash the JSON string using the HMAC-SHA256 algorithm with your API secret key.
  3. Compare the result with the signature field in the payload.
function validateSignature($payload, $apiKey, $providedSignature) {
$payloadJson = json_encode($payload);
$calculatedSignature = hash_hmac('sha256', $payloadJson, $apiKey);
return hash_equals($calculatedSignature, $providedSignature);
}

$payload = [
"event" => "fund_account.success",
"eventData" => [
  "uniqueIdentity" => "d58a8a1e-569c-41a9-9b50-44aefbf6724d",
  // Other fields...
]
];
$apiKey = 'your-secret-api-key';
$providedSignature = 'cd85269437b0543a012aa734ef1b8c11397224af08b6cbd0fbf8fc043e4487f9';

if (validateSignature($payload, $apiKey, $providedSignature)) {
return true;
} else {
return false;
}

​
Best Practices

  • Always Respond with HTTP 200: When your server receives a webhook, ensure that you respond with an HTTP 200 status code as soon as possible, even if you have not fully processed the event. This will tell Bold Bank that your server received the webhook successfully.
  • Always Validate the Webhook: To protect against malicious actors, always validate the signature of each webhook. If the signature is invalid, you should reject the request and not process the event further.
  • Handle Events Carefully: Process webhooks asynchronously to prevent long response times. Ensure that you log errors when they occur and have a mechanism for retrying failed webhook processing.
IntroductionStatuses & Codes