Webhooks allow your system to establish a communication channel with Nomba, usually via a public URL. When a payment event occurs on your account, Nomba will send a notification via this communication channel to notify you about this event.Nomba will send a POSTrequest to the public webhook URL containing the details of the event and header strictly for verifying that the webhook event originated from the Nomba system.
Established webhook process flow
This image shows an established communication via webhook URL between your system and Nomba.
It is good to note that, you must subscribe for the event type you want to get
notified on.
To set up your webhooks, navigate to the settings page and select the webhook tab on your dashboard. On this page you can set a live or test webhook URL and signature key. When you add a webhook URL, you can subscribe for the event you want to get notified on.
Set up webhook on your dashboard
Kindly ensure that your webhook URL is publicly available.
Payment Successpayment_success : Triggered when a payment is successfully credited to your Nomba account, e.g., card transaction, PayByTransfer, or PayByQR.
Payout Successpayout_success : Triggered when a payment is successfully debited from your account, e.g., funds transfer, bill payment.
Payment Failedpayment_failed : Triggered when a proposed payment attempt fails.
Payment Reversalpayment_reversal : Triggered when a payment is reversed from your account back to the customer’s account.
Payout Failedpayout_failed : Triggered when a payout transaction fails to process successfully and is not completed.
Payout Refundpayout_refund : Triggered when a payout is refunded back to your Nomba account.
Every webhook notification from Nomba includes special headers and a payload that matches the content of all supported event types. These headers will help you verify and process the request to ensure that it’s coming from Nomba, as a public URL can be accessed by anyone, so it’s to verify that all webhooks are from Nomba before giving value to your customers.A typical webhook payload will come with the following Nomba-specific headers:
A signature created using the signature key configured while creating the webhook on the Nomba dashboard
nomba-signature-algorithm
The algorithm used to generate the signature. Value is always HmacSHA256
nomba-signature-version
The version of the signature used. Value is 1.0.0 at the moment. It will keep updating as the signing process updates
nomba-timestamp
An RFC-3339 timestamp that identifies when the payload was sent.
The RFC-3339 format specifies that dates should be represented using the year,
month, and day, separated by hyphens, followed by a “T” to separate the date
from the time, and then the time represented in hours, minutes, and seconds,
separated by colons, with an optional fractional second component. Example;
2022-01-01T15:45:22Z
HTTP header names are case insensitive. Your client should convert all header
names to a standardized lowercase or uppercase format before trying to
determine the value of a header.
Since webhooks are simply HTTP POST requests, there’s a chance that malicious actors could try to send fake webhook events to your server. To protect you from this, Nomba signs each webhook payload using the signature key you set when creating the webhook. The generated signature is included in the request headers, so your server can verify that the request truly came from Nomba and not an attacker.
We recommend configuring the signature key while creating a webhook URL. While
this configuration is optional, it is important to configure the keys and
verify the signature of the payloads in order to prevent DDoS or
Man-in-the-Middle attacks.
To make sure a webhook truly comes from Nomba and hasn’t been altered, each request we send includes a signature in the header. This signature is generated using your webhook payload and the secret key you set on your dashboard.On your end, verification is straightforward:
Re-create the signature :
Use the same secret key and payload to generate a hash - HMAC signature.
Compare signatures :
Match your generated hash with the nomba-signature header we sent. If they’re the same, you can trust the webhook.
The tab below contains sample code demonstrating how to calculate the HMAC signature and compare it with the signature sent via the webhook.
Nomba allows you to pass an idempotency key using the X-Idempotent-key header. This helps prevent duplicate requests when the first request fails due to issues like network interruptions.Although our system already handles idempotency internally, we recommend that you include an idempotency key when calling endpoints such as Bank Transfer.For example, if a bank transfer request succeeds but the confirmation is lost, resending the same request with the same idempotency key ensures that:
Only the first request is processed.
A duplicate request will either return the original response if identical or throw an error if different.
This keeps your transactions safe and predictable by avoiding accidental duplicate transfers.
Always use a unique idempotency key for each request. This is best practice to ensure consistent behavior.
The following examples show how to generate a unique keys in popular programming languages.
When a webhook fails to deliver because the receiving server does not return a 2XX status code, Nomba automatically retries the request using an exponential backoff policy. This approach spaces out retries with increasing delays, preventing your server from being overwhelmed while still ensuring delivery. Both 4XX client errors and 5XX server errors will trigger this retry flow. After the first failed attempt, Nomba will make up to five additional attempts to re-deliver the webhook.The table below gives proper perspective into how failed webhooks would be retried.