Webhooks

What is a Webhook?

A webhook is a mechanism that allows real-time communication between two systems by sending an HTTP request (usually a POST request) from one application to another when a specific event occurs. Unlike traditional polling, where a system repeatedly checks for updates, webhooks push data automatically, reducing latency and improving efficiency.

In simple terms, webhooks act as event-driven notifications that alert an external system when something happens.

How Webhooks Work

Event Trigger – A specific event occurs in the source system (e.g., a bank transaction is processed).

Webhook URL – The system that needs to be notified (the receiver) provides a URL where the event data should be sent.

HTTP Request – The source system sends an HTTP POST request to the webhook URL, containing the event details in JSON or XML format.

Processing the Data – The receiving system extracts and processes the event data, taking appropriate action (e.g., updating records, notifying customers).

Acknowledgment & Retry Mechanism – The receiver responds with an HTTP status code (200 OK for success). If the request fails, the sender may retry to ensure reliable delivery.

Example of a Webhook Flow in Banking

Scenario: A Real-Time Payment Notification Webhook

Imagine a bank provides an API that allows businesses to receive real-time notifications when a customer makes a payment.

A merchant registers a webhook URL with the bank’s API to receive payment updates.

Example: https://merchant.com/webhook/payment

A customer makes a payment, and the bank’s system processes the transaction.

The bank’s system triggers a webhook event for the payment success.

An HTTP POST request is sent to the merchant's webhook URL with payment details:

{
  "event": "payment.success",
  "transaction_id": "TXN123456789",
  "amount": 5000,
  "currency": "NGN",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "status": "successful",
  "timestamp": "2025-04-03T14:30:00Z"
}

Webhook vs. API Polling: Why Webhooks Are Better?

Webhooks and API polling are two different methods for retrieving data from a system, but webhooks are generally more efficient and preferred for real-time communication.

1. Webhooks (Push Mechanism)

Webhooks send data automatically when an event occurs.

No need for the client to continuously check for updates.

Uses minimal server resources and bandwidth.

2. API Polling (Pull Mechanism)

The client must repeatedly send requests at intervals to check for updates.

Can cause high server load and increased bandwidth usage.

May lead to delays in receiving critical updates.

Comparison Table

Feature	Webhooks	API Polling
Data Delivery	Instant (push)	Delayed (pull)
Efficiency	High	Low
Server Load	Low	High (frequent requests)
Bandwidth Usage	Minimal	High
Real-time Updates	Yes	No
Reliability	Requires proper handling of retries	Can miss updates if polling interval is too long
Complexity	Requires webhook endpoint setup	Simpler but inefficient for frequent updates

When to Use Webhooks vs. API Polling

✅ Use Webhooks when:

You need real-time notifications (e.g., transaction updates, payment confirmations).

You want to reduce server load and improve efficiency.

You are integrating with event-driven systems.

✅ Use API Polling when:

The system does not support webhooks.

You need historical data or scheduled updates (e.g., daily reports).

The update frequency is low and does not require real-time notifications.

Transactions Payload

The core banking service emits transaction notifications in a structured JSON format to represent all account activities. These payloads are designed to support both basic account transactions and more complex transfer scenarios, including interbank and intrabank transfers.

The core banking service provides transaction notifications in the following format:

Regular Transactions: Simple account operations without transfer context

Interbank Transfers: External transfers with full traceability via transaction reference and session ID

Intrabank Transfers: Internal transfers represented as dual entries (debit and credit)

Regular Transaction Payload

This payload represents standard account activities such as cash deposits, withdrawals, or balance adjustments that are not tied to a transfer operation.

Each notification includes key transaction details such as:

id: Unique identifier for the transaction

nuban: The customer’s account number

amount: Transaction value

note: Description of the transaction

transactionType: Indicates whether the transaction is a Deposit or Withdrawal

balance: Account balance after the transaction

createdDate: Timestamp of when the transaction occurred

currency: Currency code (e.g., NGN)

This format is typically used for internal account operations or non-transfer-related activities.

Interbank Transfer Payloads

Interbank transfer payloads are used for transactions involving external financial institutions. These payloads extend the regular transaction structure by including a transactionReference and a detailed transferDetails object.

Key Characteristics

A unique transactionReference is provided for traceability across systems.

The transferDetails object contains all relevant metadata required for reconciliation and audit.

Transfer Direction

Interbank transactions are categorized into two types:

Inward Transfers (Deposit): Funds received from another bank into the customer’s account.

Outward Transfers (Withdrawal): Funds sent from the customer’s account to another bank.

Transfer Details Fields

The transferDetails object includes:

amount: Transfer amount

sourceBankName / destinationBankName: Names of participating banks

transactionStatus: Current status (e.g., CONFIRMED)

transactionReference / sessionId: Unique identifiers for tracking

type: Indicates transfer direction (INWARD_TRANSFER or OUTWARD_TRANSFER)

sourceAccountNUBAN / destinationAccountNUBAN: Account numbers involved

sourceAccountName / destinationAccountName: Account holder names

sourceInstitutionCode / destinationInstitutionCode: Bank identifiers

narration: Description of the transfer

This structure ensures interoperability with external payment systems and provides sufficient detail for dispute resolution and reconciliation.

Inward Transfer Payload Example

{
    "id": 1445,
    "nuban": "0020000015",
    "amount": 20,
    "note": "Inward Test - MOHAMMED BALARABE OLATEJU",
    "transactionType": "Deposit",
    "balance": 66,
    "createdDate": "2024-10-27T06:00:48Z",
    "currency": "NGN",
    "transactionReference": "000012241027065934422656001526",
    "transferDetails": {
        "amount": 20,
        "sourceBankName": "STANBICIBTC BANK",
        "transactionStatus": "CONFIRMED",
        "transactionReference": "000012241027065934422656001526",
        "sessionId": "000012241027065934422656001526",
        "type": "INWARD_TRANSFER",
        "destinationAccountNUBAN": "0020000015",
        "destinationAccountName": "Mohammed Olateju",
        "destinationInstitutionCode": "090605",
        "sourceAccountNUBAN": "0040088210",
        "narration": "Inward Test",
        "sourceInstitutionCode": "0000122",
        "destinationBankName": "Madobi Microfinance Bank",
        "sourceAccountName": "MOHAMMED BALARABE OLATEJU"
    }
}

Outward Transfer Payload Example

{
    "id": 1445,
    "nuban": "0020000015",
    "amount": 20,
    "note": "Inward Test - MOHAMMED BALARABE OLATEJU",
    "transactionType": "Withdrawal",
    "balance": 66,
    "createdDate": "2024-10-27T06:00:48Z",
    "currency": "NGN",
    "transactionReference": "000012241027065934422656001526",
    "transferDetails": {
        "amount": 20,
        "sourceBankName": "STANBICIBTC BANK",
        "transactionStatus": "CONFIRMED",
        "transactionReference": "000012241027065934422656001526",
        "sessionId": "000012241027065934422656001526",
        "type": "OUTWARD_TRANSFER",
        "destinationAccountNUBAN": "0020000015",
        "destinationAccountName": "Mohammed Olateju",
        "destinationInstitutionCode": "090605",
        "sourceAccountNUBAN": "0040088210",
        "narration": "Inward Test",
        "sourceInstitutionCode": "0000122",
        "destinationBankName": "Madobi Microfinance Bank",
        "sourceAccountName": "MOHAMMED BALARABE OLATEJU"
    }
}

Intrabank Transfer Payloads

Intrabank transfers occur between accounts within the same financial institution. These transactions generate two corresponding records:

A Withdrawal from the sender’s account

A Deposit into the recipient’s account

Both records share similar transferDetails, with differences reflecting the perspective of each account.

Key Characteristics

No external transaction reference is required since the transfer is internal.

The type is always set to INTRABANK_TRANSFER.

Both sides of the transaction are fully captured for consistency and traceability.

Transfer Details Fields

The transferDetails object includes:

amount: Transfer amount

sourceBankName / destinationBankName: Typically the same institution

transactionStatus: Status of the transfer (e.g., CONFIRMED)

narration: Transfer description

type: Always INTRABANK_TRANSFER

sourceAccountNUBAN / destinationAccountNUBAN: Accounts involved

sourceAccountName / destinationAccountName: Account holder names

Withdrawal

{
    "id": 35,
    "nuban": "0020000228",
    "amount": 1,
    "note": "Transfer Test",
    "transactionType": "Withdrawal",
    "createdDate": "2025-03-28T12:18:42Z",
    "currency": "NGN",
    "transferDetails": {
        "amount": 1,
        "sourceBankName": "Madobi MFB",
        "transactionStatus": "CONFIRMED",
        "narration": "Transfer Test",
        "sourceAccountNUBAN": "0020000228",
        "type": "INTRABANK_TRANSFER",
        "destinationAccountNUBAN": "0020001050",
        "destinationBankName": "Madobi MFB",
        "sourceAccountName": "Eyitayo Aganna",
        "destinationAccountName": "Abigail Aina"
    }
}

Deposit

{
    "id": 35,
    "nuban": "0020001050",
    "amount": 1,
    "note": "Transfer Test",
    "transactionType": "Deposit",
    "createdDate": "2025-03-28T12:18:42Z",
    "currency": "NGN",
    "transferDetails": {
        "amount": 1,
        "sourceBankName": "Madobi MFB",
        "transactionStatus": "CONFIRMED",
        "narration": "Transfer Test",
        "sourceAccountNUBAN": "0020001050",
        "type": "INTRABANK_TRANSFER",
        "destinationAccountNUBAN": "0020000228",
        "destinationBankName": "Madobi MFB",
        "sourceAccountName": "Abigail Aina",
        "destinationAccountName": "Eyitayo Aganna"
    }
}

What is a Webhook?#

How Webhooks Work#

Example of a Webhook Flow in Banking#

Scenario: A Real-Time Payment Notification Webhook#

Webhook vs. API Polling: Why Webhooks Are Better?#

1. Webhooks (Push Mechanism)#

2. API Polling (Pull Mechanism)#

Comparison Table#

When to Use Webhooks vs. API Polling#

Transactions Payload#

Regular Transaction Payload#

Interbank Transfer Payloads#

Key Characteristics#

Transfer Direction#

Transfer Details Fields#

Inward Transfer Payload Example#

Outward Transfer Payload Example#

Intrabank Transfer Payloads#

Key Characteristics#

Transfer Details Fields#

Withdrawal#

Deposit#

What is a Webhook?

How Webhooks Work

Example of a Webhook Flow in Banking

Scenario: A Real-Time Payment Notification Webhook

Webhook vs. API Polling: Why Webhooks Are Better?

1. Webhooks (Push Mechanism)

2. API Polling (Pull Mechanism)

Comparison Table

When to Use Webhooks vs. API Polling

Transactions Payload

Regular Transaction Payload

Interbank Transfer Payloads

Key Characteristics

Transfer Direction

Transfer Details Fields

Inward Transfer Payload Example

Outward Transfer Payload Example

Intrabank Transfer Payloads

Key Characteristics

Transfer Details Fields

Withdrawal

Deposit