Webhooks

A webhook notifies you about a change in the status of an account on your platform. These notifications are delivered to your defined webhook URL provided and updated through the Business API dashboard. You may use these notifications to perform additional tasks on your application as it suits your business goals. The Webhook notifications provide information on transactions happening on your internal accounts.

The Kuda Business API webhooks are HTTP calls triggered by specific events. The webhooks replace regular API calls with instant, real-time notifications. It can be set up on your dashboard by specifying a URL we would send POST requests to you whenever an event is of interest. Each webhook notification contains an eventType that specifies which type of event triggered the webhook notification.

To process notifications, you need to:

Expose an endpoint on an open server

We can send notifications as HTTP callbacks (webhooks) to an endpoint on a server that must be open. To receive webhooks, you must have a server that:

1. Has an endpoint that can receive JSON requests

2. Depending on your network and security requirements, you might also need to add our IP address to your firewall's whitelist.

Subscribe to webhook notifications

To configure webhook notifications:

• Login to your

  Kuda Business Account

  dashboard

• Go to Business API > Settings > Webhooks.

• Enter your Notification URL

• Add your username and password.

• Click “Submit” to complete

You can also download the user guide below:

Accept the notifications

To ensure that your server correctly accepts notifications, we require you to acknowledge every notification with an HTTP 200 response code. If we don't receive this response within 10 seconds, for example, your server is down, all notifications to your endpoint will be queued and re-triggered. For more information, refer to Queued Notifications. When your server receives a notification:

1. Save the notification in your database.
2. Acknowledge the notification with the following HTTP response status code
3. Apply your business logic.

Ensure you acknowledge the notification before applying any business logic, because a breakage in your business logic could otherwise prevent important updates from reaching your system. A webhook notifies you about a change in the status of an account on your platform. These notifications are delivered to your defined webhook url provided and updated through the Business API dashboard. You may use these notifications to perform additional tasks on your application as it suits your business goals. The Webhook notifications provide information on transactions happening on your internal accounts.

Webhook Types

There are currently three webhook types available to you:

• Transactions - This event type pertains to transactions involving inward and outward operations.

• Bills - This refers to all events related to bill payments.

Parameters for Transactions

To receive a webhook event notification, set your rules for the post route for your application.

Sample Webhook Event Format for Transactions

{
    "eventType":   "Transaction.Notification",
    "payingBank":   "Kuda",
    "amount":   36000,
    "transactionDate":   "2023-12-08T00:00:00",
    "transactionReference":   "231208609730",
    "accountName":   "(9raPoint)-Odoro  Christian",
    "accountNumber":   "2056707065",
    "narrations":   "REF: 705847638800 9rapoint:  null",
    "transactionType":   "Credit",
    "senderName":   "9rapoint-hermina",
    "senderAccountNumber":   "3000002708",
    "recipientName":   "(9raPoint)-Odoro Christian",
    "InstrumentNumber":   "853254207041017463",
    "sessionID":   null,
    "clientRequestRef":   "853254207041017463",
    "transactionScope":   null
}

Sample Webhook Event Format for Bills

{
    "BillRequestRef":   "",
    "BillResponseReference":   "",
    "Pin": {
        "Number": "",
        "Serial": "",
        "Instructions": "",
    },
    "BillerName":   "",
    "KudaAccountNumber":   "",
    "TransactionAmount":   "",
    "CustomerIdentifier":   "",
    "BillType":   "",
}

Bulk Retrigger Webhook

This method initiate a bulk webhook retrigger using the transaction reference number.

{
    "serviceType": "BULK_WEBHOOK_RETRIGGER",
    "requestRef": "ref1234l",
    "Data": [
        {
            "AccountNumber": "3000069125",
            "EntryCode": "C339-23",
            "Reference": "240319386165",
        },
        {
            "AccountNumber": "3000069125",
            "EntryCode": "D305",
            "Reference": "240319386165",
        },
    ]
}

{
    "message": "Retrigger Successful.",
    "status": true,
    "data": null
}

Test and Go Live

You will be required to test your webhook notifications on production only. Once you are satisfied that they are working according to requirements, you can go live.