# 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.<br>

> **Sample Payload:**
>
> If your webhook URL is valid, you will receive a payload like this:

```json
{
  "orderId": "dpkg-1234",
  "txId": "cf2efce87f85a16e4bac7d0b3cdd548700f074fa375c0640b0da02155266d200",
  "amount": "6.9",
  "confirmations": 1,
  "status": "COMPLETED",
  "type" : "INVOICE",
  "coin" : "{coinSmobol}",
  "network" : "{networkName}",
  "trackingCode" : 10000
  "isWallet" : false
}
```

### Whitelist our IP address <a href="#id-2-whitelist-our-ip-address" id="id-2-whitelist-our-ip-address"></a>

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

`1.1.1.1`, `1.1.1.1`, `1.1.1.1`<br>

### 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`.<br>
* The resulting hash value is included in the `X-Hash` header of the webhook call.<br>
* 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) <a href="#id-3-verify-your-invoice-optional" id="id-3-verify-your-invoice-optional"></a>

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

<mark style="color:green;">`POST`</mark> `https://api.nebulox.io/api/invoice/verify`

Call this method to verify your invoice

#### Request Body

| Name                                           | Type   | Description                      |
| ---------------------------------------------- | ------ | -------------------------------- |
| apiKey<mark style="color:red;">\*</mark>       | string | Your API key                     |
| trackingCode<mark style="color:red;">\*</mark> | number | The tracking code of the invoice |

{% tabs %}
{% tab title="201: OK Invoice verfication" %}

```json
{
    "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": {}
}
```

{% endtab %}
{% endtabs %}

```javascript
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);
  });

```

{% hint style="success" %}
**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.
{% endhint %}

##


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nebulox.io/reference/api-reference/webhook-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.