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.

​
Webhook Overview

​
How to set up your webhook URL

Log in to your Bold Bank account, navigate to settings, and provide the URL endpoint where webhook events should be delivered.

​
Webhook payload structure

Each webhook payload contains these fields:

  • event: The event type (for example, bankTransfer.success).
  • eventData: The event payload body.
  • signature: HMAC-SHA256 signature used for verification.

Common fields inside eventData include:

  • sessionId
  • productType
  • amount
  • netAmount
  • fee
  • commission
  • transactionStatus (SUCCESS, FAILED, or PROCESSING)
  • transactionReference
  • customerReference
  • comment
  • createdAt
  • transactionAccount
  • transactionType (CREDIT or DEBIT)

Event-specific objects such as sender, beneficiary, details, or metadata can also appear.

{
  "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"
}

Always inspect eventData.transactionStatus to determine the real state of a transaction.

​
Partner integration events (Outlets)

Partners using Outlets receive three additional events in addition to the standard ones.

EventWhen it firesPurpose
outlet.createdAfter POST /outlets succeedsConfirms outlet and wallets are usable.
walletSweptIntra.successfulAfter an auto-sweep moves funds from an outlet collection walletReconciliation event with sweepReference.
internalTransfer.successfulAfter POST /transfer/internal settlesConfirms internal wallet movement.

Outlets also receive fundAccount.success and bankTransfer.success / bankTransfer.failed with the same payload shape documented above.

​
Signature Validation

To verify authenticity, compute HMAC-SHA256 and compare to the payload signature.

Your x-api-key is also the webhook signing secret. Keep it server-side only, never expose it in client applications, and rotate it immediately if leaked.

​
Validation Steps

  1. Extract only the eventData object.
  2. Serialize eventData as minified JSON.
  3. Compute HMAC-SHA256 using your x-api-key.
  4. Compare the hex digest with signature using a constant-time comparison.
function validateSignature(array $payload, string $apiKey): bool {
    $eventDataJson = json_encode($payload['eventData'], JSON_UNESCAPED_SLASHES);
    $calculated = hash_hmac('sha256', $eventDataJson, $apiKey);
    return hash_equals($calculated, $payload['signature']);
}

​
Best Practices

  • Acknowledge fast with HTTP 2xx after persisting the payload.
  • Make handlers idempotent because retries can happen.
  • Always validate signature before processing.
  • Process asynchronously to keep webhook endpoints responsive.
AuthenticationStatuses & Codes