Skip to main content

​
Overview

Webhooks are a communication mechanism that enables event-driven notifications between systems. When an event occurs in Novac system, such as a payment being completed or a payout being initiated. Novac automatically sends a real-time notification to the merchant’s system. This means your system doesn’t have to constantly poll Novac for updates. Instead, you simply provide Novac with a publicly accessible webhook URL, and Novac will send a POST request to that endpoint whenever a relevant event occurs.
Webhook URLs must be publicly accessible at all times in order to receive notifications.
This whole process makes it easier to keep your system in sync with payment statuses when you integrate with Novac.

​
Process Flow

This sequence diagram illustrates the process flow from initiating a checkout payment to its completion, involving the customer, the merchant system, and Novac. With Novac payment, you don’t need to manually subscribe to webhook events.
Once you configure your webhook URLs in the dashboard, Novac automatically sends notifications whenever relevant events occur in your account.

​
Setting Up Your Webhook

1

Step 1 - Log in to your Novac Dashboard

Sign in to your Novac Dashboard using your account credentials.
2

Step 2 - Navigate to Webhooks

From the sidebar menu, go to Settings, Click on API settings tab.
This is where you can configure both test and live webhook URLs.
3

Step 3 - Add your Webhook URLs and Click on Save

Enter the publicly accessible URLs where you want to receive webhook notifications.
  • Add a test webhook URL for test transactions.
  • Add a live webhook URL for real payments in production.
  • Ensure the URLs are always available and accept POST requests.
Novac will send an HTTP POST request to these URLs after a transaction is completed.

​
Notification Types

Notify TypeDescriptionCommon Scenario
successfulPayment or transaction was processed successfully.A customer’s card or bank transfer succeeded.
failedTransaction attempt failed or was declined.Insufficient funds or incorrect payment details.
reversedA previously successful transaction was reversed.Refunds or chargeback scenarios.
abandonedTransaction was started but not completed.Customer exited before finalizing payment.

​
Handling Webhook payload

Each webhook request payload sent from Novac follows the structure below:
Webhook format
{
  "data": {
    "id": 0,
    "card": {
      "type": "",
      "token": "",
      "issuer": "",
      "country": "",
      "last4Digits": "",
      "first6Digits": ""
    },
    "amount": 300,
    "domain": "live",
    "status": "failed | reversed | successful | abandoned",
    "channel": "",
    "currency": "NGN",
    "customer": {
      "id": 0,
      "name": "",
      "email": "",
      "customerCode": ""
    },
    "requestIp": "",
    "redirectUrl": "",
    "chargedAmount": 0,
    "transactionFee": 0,
    "transferDetail": {
      "bankCode": "",
      "bankName": "",
      "sessionId": "",
      "accountNumber": "",
      "originatorName": "",
      "creditAccountName": "",
      "originatorAccountNumber": ""
    },
    "checkoutMetadata": "{}",
    "authorizationCode": "",
    "paymentDescriptor": "NOVAC",
    "gatewayResponseCode": "",
    "transactionReference": ""
  },
  "notify": "transaction | wallet_funding | banktransfer",
  "notifyType": "failed | reversed | successful | abandoned"
}
The webhook structure provides complete details about the transaction event, including customer, card, and transfer details.
For best practices, after receiving a webhook, we recommend that you validate the transaction status by using the verify transaction endpoint.

​
Verifying Webhook Source

Webhooks are publicly available URLs; this means that anyone can fake a webhook sample and send a fake request to your system. It’s important to verify that all webhooks received are from Novac to avoid man-in-the-middle attacks. To verify the webhook your system received. We advise merchants to allow requests from a dedicated network address. We provide our IP address, and you should verify that every webhook request comes from it. This method is called IP whitelisting. Novac public IP address: 18.233.137.110
It’s important to know that we can add to this IP at any point in time; however, we will inform our merchant before doing so.

​
What is IP whitelisting?

IP whitelisting is a mechanism used on the server-side as a filter; it helps ensure only a pre-approved set of IP addresses or IP ranges have the right to hit a server. If a request comes from an unknown IP address, your server will reject it.
You must use IP whitelisting as a layer of protection for incoming webhooks. If your system is behind a proxy or load balancers, you must obtain the real client IP.

​
Validate incoming webhook IP address.

To validate incoming webhooks, we have provided sample codes to give you a better context on how to go about this depending on your programming language. 
// simple-ip-whitelist.js
const express = require('express');
const app = express();

const ALLOWED_IPS = ['18.233.137.110']; 

app.set('trust proxy', true); // check for proxy or load balancer

function ipWhitelist(req, res, next) {
  const clientIp = (req.ip || '').replace(/^::ffff:/, ''); // normalize IPv4-mapped IPv6
  if (ALLOWED_IPS.includes(clientIp)) return next();
  console.warn(`Blocked webhook from IP: ${clientIp}`);
  return res.status(403).send('Forbidden');
}

app.post('/webhook', ipWhitelist, express.json(), (req, res) => {
  // handle verified webhook here
  res.status(200).send({received: true});
});

app.listen(3000, () => console.log('Webhook listener on :3000'));
It is crucial to thoroughly validate and properly test this with a test webhook before going live.
In a case where your system is behind a proxy such as nginx. You can do a double validation, e.g., first validate in your config file that the webhook is coming from the Novac network address. If successful, you can then route this webhook to the endpoint defined in your system, which also runs another check to validate the request.

​
Retries

To ensure reliable delivery, Novac automatically retries webhook notifications when your server fails to respond with a successful 200 OK status code.
Your webhook endpoint must always respond with HTTP 200 to acknowledge receipt of the event. Any other status code (e.g., 4xx or 5xx) will trigger a retry attempt.
Retry Policy
ParameterDescription
Retry Count3 attempts
Retry IntervalEvery 5 seconds between retries
ConditionTriggered when Novac doesn’t receive a 200 OK response from your webhook endpoint