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 provides transaction notifications in the following format:

Regular Transaction Payload

Transfer Payload

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

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#

Transfer Payload#