> For the complete documentation index, see [llms.txt](https://konnadex-docs.gitbook.io/konnadex-technologies/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://konnadex-docs.gitbook.io/konnadex-technologies/webhooks.md).

# 🪝Webhooks

Listen to webhook events whenever certain actions occurs

#### What are webhooks? <a href="#what-are-webhooks" id="what-are-webhooks"></a>

Webhooks are a way for you to subscribe to events that occur when an event involving your business occurs. This guide will walk through what webhooks are and how you can use them to get started with integrating them into your application.

A webhook URL is an endpoint on your server where you can receive notifications about such events. When an event occurs, we'll make a POST request to that endpoint, with a JSON body containing the details about the event, including the type of event and the data associated with it.

Rather than continuously polling the server to check if the state has changed, webhooks provide information to you as it becomes available, which is a lot more efficient and beneficial for developers.

Here are some sample webhook payloads for deposit transactions:

```javascript
{
  "event": "GATEWAY_DEPOSIT_TRANSACTION",
  "message": "Transaction successful",
  "data": {
    "integratorId": "65d91172249711be4bea993f",
    "amount": 2.6037,
    "fee": 0.0263,
    "amountPaid": "2.63",
    "asset": "USDT",
    "blockchain": "BSC",
    "fiatAmount": "4000.00",
    "fiatCurrency": ["NGN","USD","EUR","GBP","GHS","AUD","JPY"]
    "rate": "1518.4",
    "hash": "0x6e1e5c57378a251e3fd4238c0d7828d76f75b18b843adfc608a8a125ef4afa31",
    "status": "complete",
    "reference": "PLK_61t4p744ltn6j3wz",
    "paymentReference": "KDX|ltn6je0e|yfiwi",
    "source": "COLLECTIONS",
    "senderAddress": "0x3f5d53EB3cD50D4eFD9Cc9ae1f73097C4072f6f0",
    "recipientAddress": "0x3f5d53EB3cD50D4eFD9Cc9ae1f73097C4072f6f0",
    "createdAt": "2024-03-11T16:50:38.328Z",
    "metadata": {
      "phone": "+1204",
      "fullname": "Ugochukwu Anthony",
      "email": "test@gmail.com",
      "address": "38, Galloway St ,Enugu ,Nigeria"
    }
  }
}
```

#### Enabling webhooks <a href="#enabling-webhooks" id="enabling-webhooks"></a>

You can specify your webhook URL on your dashboard where we will send `POST` requests to whenever an event occurs.

Here's how to set up a webhook on your Konnadex account:

* Login to your dashboard and click on the **Settings**
* Navigate to the **API Keys and Webhooks tab**
* specify your webhook URL and click on **Update**

{% hint style="info" %}
When testing, you can get an instant webhook URL by visiting the webhook site. This will allow you to inspect the received payload without having to write any code or set up a server.
{% endhint %}

#### Validating webhooks signature <a href="#validating-webhooks-signature" id="validating-webhooks-signature"></a>

Every webhook event payload will contain a hashed authentication signature in the header which is computed by generating a hash from concatenating your API key and request body, using the HMAC SHA256 hash algorithm.

To verify this signature came from Konnadex, you simply have to generate the HMAC SHA256 hash and compare it with the signature received.

```javascript
var crypto = require('crypto');
var secret = process.env.SECRET_KEY;
// Using Express
app.post("/my/webhook/url", function(req, res) {
const hmac = crypto.createHmac('sha256', 'SECRET_HERE')
const hash = hmac.update(JSON.stringify(payloadBody)).digest('hex')
const signature=req.headers['k-signature'];
const isValid =  crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature))
  
    if (isValid) {
    // Retrieve the request's body
    var event = req.body;
    // Do something with event  
    }
    res.send(200);
});
```

#### Responding to webhooks request <a href="#responding-to-webhooks-request" id="responding-to-webhooks-request"></a>

You must respond with a `200 OK` status code. Any other response codes outside of the `2xx` range, we will consider it will be considered as a failure, including `3xx` codes. **We don't care about the response body or headers**.

{% hint style="info" %}
If we don't get a 200 OK status code, we'll retry the webhook every one minute for the next 24 hours.
{% endhint %}

#### Supported Webhooks types. <a href="#supported-webhooks-types" id="supported-webhooks-types"></a>

Here are the webhooks request types we support. We'll add more to this list as we keep adding webhook support for different API operations in the future.

| WebHook Type         | Description                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| DEPOSIT\_TRANSACTION | A deposit transaction has occurred. It could have a status of: `complete`, `failed,` `processing`, `underpay`, `overpay` |
| WITHDRAWAL\_SUCCESS  | <p>Indicates a successful withdrawal transaction has been completed. complete<br></p>                                    |
| WITHDRAWAL\_REQUEST  | Represents a request to initiate a withdrawal transaction.                                                               |

**Example: Withdrawal WebHook**

```javascript
{
  "event": "WITHDRAWAL_SUCCESS", 
  "message": "Withdrawal success",
  "data": {
    "integratorId": "6516b1158a73710b161bdc95",
    "id": "88cc6cca-4d0d-4889-a3d6-ffb702b933cf",
    "fee": 0.2,
    "hash": "0xa2b04f7deb59415430590d5f890f24dea6427506861f07c5ffc19bc5a2fa4b2b",
    "amount": 2,
    "address": "0x337610d27c682E347C9cD60BD4b3b107C9d34dDd",
    "assetId": "USDT",
    "blockchainId": "BSC"
  }
}

{
  "event": "WITHDRAWAL_REQUEST",
  "message": "Withdrawal request",
  "data": {
    "integratorId": "6516b1158a73710b161bdc95",
    "id": "88cc6cca-4d0d-4889-a3d6-ffb702b933cf",
    "fee": 0.2,
    "amount": 2,
    "address": "0x3f5d53EB3cD50D4eFD9Cc9ae1f73097C4072f6f0",
    "assetId": "USDT",
    "balance": 605.149,
    "blockchainId": "BSC"
  }
}
```