Webhook Setup Guide

Webhook Connection and URL

When an incoming transaction occurs, Nebulox will send a POST request to the specified webhook URL, including a payload with the transaction details.

Setup Procedure:

To establish your webhook connection, follow these steps:

1. Provide a Valid Webhook URL: Ensure the URL is correct and ready to receive POST requests.

2. Whitelist Our IP Address: Allow requests from our IP address to pass through your firewall or security settings.

3. Hmac-Based Security for Webhook calls : We strongly suggest implementing this validation in your code to ensure the integrity and authenticity of the webhook requests.

4. Verify Your Invoice (Optional): Optionally, you can verify your invoice for added security.

Providing a Valid Webhook URL

When configuring a new Nebulox gateway, it is crucial to provide a valid webhook URL. This ensures that Nebulox can seamlessly transmit real-time notifications for new transactions, facilitating smooth integration and enabling automated operations within your payment processing flow.

Sample Payload:

If your webhook URL is valid, you will receive a payload like this:

{
  "orderId": "dpkg-1234",
  "txId": "cf2efce87f85a16e4bac7d0b3cdd548700f074fa375c0640b0da02155266d200",
  "amount": "6.9",
  "confirmations": 1,
  "status": "COMPLETED"
}

Whitelist our IP address

After configuring your URL, please ensure not to block requests from Nebulox. Webhooks will be triggered from our servers.

1.1.1.1, 1.1.1.1, 1.1.1.1

HMAC-Based Security for Webhook Calls(Optional)

To enhance the security of webhook calls, an HMAC (Hash-based Message Authentication Code) mechanism has been implemented. This mechanism adds an X-Hash header to the request. The HMAC is generated using the SHA256 algorithm and the gateway API KEY as the secret key.

• HMAC Algorithm: SHA256

• Key Used: Gateway API KEY

• Header Name: X-Hash

Implementation:

• The X-Hash header is computed by applying the SHA256 HMAC algorithm to the webhook request body using the API KEY.

• The resulting hash value is included in the X-Hash header of the webhook call.

• The server receiving the webhook should validate the X-Hash value by recomputing it using the received payload and then comparing it to the X-Hash value provided in the header.

Verify your invoice (Optional)

Optionally, you can use the provided API to verify incoming invoices at your URL. This security check is recommended as an additional step to thwart any potential malicious activity.\

Optionally, you can utilize the provided API to verify incoming invoices at your specified URL. This security check is recommended as an additional step to thwart any potential malicious activity.

Verify your invoice

POST https://api.nebulox.io/api/invoice/verify

Call this method to verify your invoice

Request Body

Name	Type	Description
apiKey*	string	Your API key
trackingCode*	number	The tracking code of the invoice

201: OK Invoice verfication

{
    "message": "Operation was successful.",
    "result": {
        "amount": "10.47657961",
        "paidAmount": "0.00000000",
        "baseCurrency": "EUR",
        "id": "f91fa492-5858-4607-91e9-7ef484e36857",
        "trackingCode": 100061,
        "orderId": "HIX-2112e",
        "price": 1,
        "description": "test",
        "itemName": "TITAB",
        "from": "instagram 1",
        "status": "EXPIRED",
        "expirationDate": "2023-12-23T11:01:40.993Z",
        "created_at": "2023-12-23T09:21:41.423Z",
        "updated_at": "2024-01-06T09:46:12.000Z",
        "gateway": null,
        "address": "TSwEBXcr6mGazCTCpoaNgrN2S2MLTMs1ZW",
        "network": {
            "name": "Tron"
        },
        "coin": {
            "name": "Tron",
            "symbol": "TRX"
        },
        "transactions": [],
        "url": "https://nebulox.io/app/user-invoice/f91fa492-5858-4607-91e9-7ef484e36857",
        "expirationRemainingTime": 0
    },
    "meta": {}
}

const axios = require('axios');

axios.post('https://api.nebulox.io/api/invoice/verify', {
    apiKey: "YOUR_API_KEY",
    trackingCode: 100030
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.error(error);
  });

Good to Know: Ensure that your Webhook URL is not only correctly set up to accept incoming POST requests but also configured accurately within Nebulox's settings. This meticulous setup guarantees seamless reception of timely updates about new transactions, allowing you to stay informed and responsive to the activities related to your provided address.