Bokumonie API Docs
    • Bokumonie API Documentation
    • Auth
      • Authentication
        GET
    • Payout
      • Initiate payout
        POST
      • Get a Payout
        GET
      • Get Payout Summary
        POST
      • Get payouts
        GET
    • Wallet
      • Get Balance
        GET
    • Webhook Notification

    Webhook Notification

    The hashing algorithm used for the webhook signature is HMAC-SHA256 (Hash-based Message Authentication Code with SHA-256).

    🔍 Explanation#

    Algorithm: HMAC-SHA256
    Input: JSON-encoded payload
    Secret: Your webhook secret key
    Output: A hexadecimal string (64 characters)

    📁 How To Verify the Signature#

    📁 PHP Verification Example#

    📁 JavaScript/Node.js Verification Example#

    📁 Python Verification Example#

    📁 Ruby Verification Example#

    📁 curl Example to Test Your Webhook#

    🔐 Why HMAC-SHA256?#

    1.
    Security: SHA-256 is a cryptographically secure hash function
    2.
    Integrity: HMAC ensures both authenticity and integrity of the message
    3.
    Industry Standard: Used by Stripe, GitHub, and many other webhook providers
    4.
    Performance: Fast and efficient for webhook payloads
    5.
    No Replay Attacks: Combined with timestamp in payload prevents replay attacks

    📁 Recommended: Add Timestamp to Prevent Replay Attacks#

    For better security, you should also verify the timestamp:

    📁 Sample Notifications#

    The structure of the data field is the same as the object structure in the Rest API.
    transfer.initiated
    transfer.success
    transfer.failed
    // Transfer initiated event
    
    {
    "event": "transfer.initiated",
    "timestamp": "2026-04-05T18:38:54.734510Z",
    "webhook_id": "a1688ad2-b1dc-4006-8e20-cd6b739d8cb5",
    "attempt": 1,
    "data": {
       "status": "Pending",
       "transaction_id": "TXN-BOK-CE5B34C8CABC6EF5B5A431045A",
       "amount": 10,
       "fee": 0.05,
       "total_amount": 10.05,
       "currency": "SLE",
       "description": null,
       "customer": {
           "name": "John Doe",
           "wallet_id": "5553881136",
           "recipient": "0427570182"
       },
       "payment_method": {
           "provider": "ecobank",
           "type": "bank",
           "country_code": "232"
       },
       "provider_response": {
           "provider_reference": "4e181ac6-7b6a-4faa-ab3a-c0d3ff05c85b",
           "code": "09",
           "transfer_id": "9fa31dd9-a38e-4814-8a30-0cba981b6920"
       },
       "metadata": {
           "key1": "value",
           "key2": "value"
       }
    }
    }
    
    The HMAC-SHA256 algorithm provides a secure way to verify that webhooks are genuinely from Bokumomie system and haven't been tampered with during transmission!
    Modified at 2026-04-06 08:59:01
    Previous
    Get Balance
    Built with