Skip to main content

​
Overview

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.

​
Set up webhook event

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.

​
Supported Events

  • Payment Success payment_success : Triggered when a payment is successfully credited to your Nomba account, e.g., card transaction, PayByTransfer, or PayByQR.
  • Payout Success payout_success : Triggered when a payment is successfully debited from your account, e.g., funds transfer, bill payment.
  • Payment Failed payment_failed : Triggered when a proposed payment attempt fails.
  • Payment Reversal payment_reversal : Triggered when a payment is reversed from your account back to the customer’s account.
  • Payout Failed payout_failed : Triggered when a payout transaction fails to process successfully and is not completed.
  • Payout Refund payout_refund : Triggered when a payout is refunded back to your Nomba account.

​
Webhook headers

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: 
nomba-signature: 0zzATkAuEta5kpKVCExReupW/XglCk/re51P4jiDJ9c=
nomba-sig-value: 0zzATkAuEta5kpKVCExReupW/XglCk/re51P4jiDJ9c=
nomba-signature-algorithm: HmacSHA256
nomba-signature-version: 1.0.0
nomba-timestamp: 2023-03-31T05:56:47Z
HeaderDescription
nomba-signatureA signature created using the signature key configured while creating the webhook on the Nomba dashboard
nomba-signature-algorithmThe algorithm used to generate the signature. Value is always HmacSHA256
nomba-signature-versionThe version of the signature used. Value is 1.0.0 at the moment. It will keep updating as the signing process updates
nomba-timestampAn 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.

​
Webhook payload

The content of the payload is a JSON object and it gives details about the event that has been triggered.
FieldTypeDescription
event_typeStringThe event type that was triggered
request_idString (UUID)A unique request identifier useful for tracking messages
dataObject (JSON)An object describing the details of the triggered event
{
    "event_type": "payment_success",
    "requestId": "999111df-9f20-4cf8-8740-3XXXXXXXXX",
    "data": {
        "merchant": {
            "walletId": "5f04b9ee600f1c03XXXXXXXXX",
            "walletBalance": 732233.66,
            "userId": "000000ab-154e-4a11-a0cf-23XXXXXXXXX"
        },
        "terminal": {},
        "transaction": {
            "aliasAccountNumber": "0010721887",
            "fee": 150,
            "sessionId": "100004240726191726003XXXXXXXXX",
            "type": "vact_transfer",
            "transactionId": "API-VACT_TRA-067fg-sdf78ghy-fd7f-4567-b404-313XXXXXXXXX",
            "aliasAccountName": "Bestbrains-Kunle Oyetunji",
            "responseCode": "",
            "originatingFrom": "api",
            "transactionAmount": 1000,
            "narration": "Transfer from Kunle Nnaji",
            "time": "2025-05-26T12:34:24Z",
            "aliasAccountType": "VIRTUAL"
        },
        "customer": {
            "bankCode": "305",
            "senderName": "Kunle Nnaji",
            "bankName": "Paycom (Opay)",
            "accountNumber": "9035418377"
        }
    }
}

​
Webhook signature verification

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:
  1. Re-create the signature : Use the same secret key and payload to generate a hash - HMAC signature.
  2. 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.
CalculateHMAC.go
      package main

      import (
          "crypto/hmac"
          "crypto/sha256"
          "encoding/base64"
          "encoding/json"
          "fmt"
          "log"
          "strings"
      )

      // --- Struct Definitions for JSON Mapping ---

      type Payload struct {
          EventType string `json:"event_type"`
          RequestID string `json:"requestId"`
          Data      Data   `json:"data"`
      }

      type Data struct {
          Merchant    Merchant    `json:"merchant"`
          Terminal    map[string]interface{} `json:"terminal"`
          Transaction Transaction `json:"transaction"`
          Customer    Customer    `json:"customer"`
      }

      type Merchant struct {
          WalletID       string  `json:"walletId"`
          WalletBalance  float64 `json:"walletBalance"`
          UserID         string  `json:"userId"`
      }

      type Transaction struct {
          AliasAccountNumber   string  `json:"aliasAccountNumber"`
          Fee                  float64 `json:"fee"`
          SessionID            string  `json:"sessionId"`
          Type                 string  `json:"type"`
          TransactionID        string  `json:"transactionId"`
          AliasAccountName     string  `json:"aliasAccountName"`
          ResponseCode         string  `json:"responseCode"`
          OriginatingFrom      string  `json:"originatingFrom"`
          TransactionAmount    float64 `json:"transactionAmount"`
          Narration            string  `json:"narration"`
          Time                 string  `json:"time"`
          AliasAccountReference string `json:"aliasAccountReference"`
          AliasAccountType     string  `json:"aliasAccountType"`
      }

      type Customer struct {
          BankCode     string `json:"bankCode"`
          SenderName   string `json:"senderName"`
          BankName     string `json:"bankName"`
          AccountNumber string `json:"accountNumber"`
      }

      // --- Core Logic ---

      func main() {
          hooksCron2()
      }

      func hooksCron2() {
          payloadJSON := `
          {
          "event_type": "payment_success",
          "requestId": "45f2dc2d-d559-4773-bba3-2d5ec17b2e20",
          "data": {
              "merchant": {
              "walletId": "6756ff80aafe04a795f18b38",
              "walletBalance": 6052,
              "userId": "b7b10e81-e57d-41d0-8fdc-f4e23a132bbf"
              },
              "terminal": {},
              "transaction": {
              "aliasAccountNumber": "5343270516",
              "fee": 5,
              "sessionId": "IFAP-TRANSFER-46501-e0339485-1a2f-4b43-9bd5-fec9649e5928",
              "type": "vact_transfer",
              "transactionId": "API-VACT_TRA-B7B10-0435b274-807a-4bc7-8abe-9dbb4548fd7a",
              "aliasAccountName": "ZAXBOX/EZENNA NWACHUKWU",
              "responseCode": "",
              "originatingFrom": "api",
              "transactionAmount": 10,
              "narration": "Habiblahi Hamzat Transfer 10.00 To ZAXBOX/EZENNA NWACHUKWU - Nomba",
              "time": "2025-09-29T10:51:44Z",
              "aliasAccountReference": "654f7c80bd4a510c90fb7f92",
              "aliasAccountType": "VIRTUAL"
              },
              "customer": {
              "bankCode": "090645",
              "senderName": "Habiblahi Hamzat",
              "bankName": "Nombank",
              "accountNumber": "9617811496"
              }
          }
          }`

          signatureValue := "Kt9095hQxfgmVbx6iz7G2tPhHdbdXgLlyY/mf35sptw="
          nombaTimeStamp := "2025-09-29T10:51:44Z"
          secret := "HkatexKDZg7CLWy96q5sfrVHSvtoz92B"

          mySig, err := generateSignature(payloadJSON, secret, nombaTimeStamp)
          if err != nil {
              log.Fatalf("Error generating signature: %v", err)
          }

          log.Printf("Generated signature [%s]", mySig)
          log.Printf("Expected signature [%s]", signatureValue)

          if strings.EqualFold(signatureValue, mySig) {
              log.Println(">>>>>>> Signatures match <<<<<<<<<")
          } else {
              log.Println("<<<<<<<<< Signatures did not match >>>>>>>>>")
          }
      }

      func generateSignature(payloadJSON, secret, timeStamp string) (string, error) {
          var payload Payload
          if err := json.Unmarshal([]byte(payloadJSON), &payload); err != nil {
              return "", fmt.Errorf("error parsing JSON payload: %w", err)
          }

          transaction := payload.Data.Transaction
          merchant := payload.Data.Merchant

          transactionResponseCode := transaction.ResponseCode
          if transactionResponseCode == "null" {
              transactionResponseCode = ""
          }

          // Construct the exact signature payload as in Java
          hashingPayload := fmt.Sprintf(
              "%s:%s:%s:%s:%s:%s:%s:%s:%s",
              payload.EventType,
              payload.RequestID,
              merchant.UserID,
              merchant.WalletID,
              transaction.TransactionID,
              transaction.Type,
              transaction.Time,
              transactionResponseCode,
              timeStamp,
          )

          log.Printf("::: payload to hash --> [%s] :::", hashingPayload)

          // Generate HMAC SHA256 and encode Base64
          h := hmac.New(sha256.New, []byte(secret))
          h.Write([]byte(hashingPayload))
          hash := h.Sum(nil)

          return base64.StdEncoding.EncodeToString(hash), nil
      }

​
Idempotency in Nomba

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. 
package main

import (
	"fmt"
	"github.com/google/uuid"
)

func main() {
	idempotentKey := uuid.New().String()
	fmt.Println(idempotentKey)
}

​
Retrying Failed Webhooks

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.
No of RetriesWaitTime (in Seconds)WaitTime (in Mins)
1120 secs2 mins
2280 secs~ 5 mins
3640 secs~ 11 mins
41440 secs24 mins
53200 secs~ 53 mins