Documentation - Notus API

In this guide, we'll show you how to build and deploy a webhook service for receiving event data from Notus API. Whether you're using Node.js or any other programming language, this guide will help you set up a webhook server to seamlessly receive events like swaps or transactions.

We'll walk you through creating a webhook endpoint, validating payloads, and testing your webhook service. By the end, you’ll have a fully functioning webhook server to integrate with Notus API.

const express = require('express');
const crypto = require('node:crypto');

const app = express();
app.use(express.json());

const secret = "<webhook-secret>" // get on dashboard

app.post('/webhooks/swap', (req, res) => {

    const signature = req.headers['x-signature'];

    const digest = crypto.createHmac('sha256', secret)
        .update(JSON.stringify(req.body), 'utf-8')
        .digest('hex')

    const isValidSignature = digest === signature

    if (!isValidSignature) {
        return res.status(401).send('Unauthorized');
    }

    res.status(200).end();
});


app.listen(3000, () => {
    console.log('Example app listening on port 3000!');
});

Example Webhook Event Payload

Here is an example payload sent by the webhook for a swap event:

{
  "event": "notification",
  "createdAt": "2024-11-26T18:49:41.001Z",
  "payload": {
    "id": "0xbe375eca954688f2c6e9d3f06acb3b83d5968cf647e1de3b9aba4ba542dd64c7",
    "txHash": "0x140b1dc6aff606fc96a5dcbb3bfe3372a9571e1b4e74366ac41b194c00921d1d",
    "status": "COMPLETED",
    "transactionType": "CROSS_SWAP",
    "tokenIn": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "tokenOut": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
    "amountIn": "2",
    "amountOut": "1.811373",
    "maxGasFeeToken": "0.079504",
    "maxGasFeeNative": "0.153818483173099014",
    "payFeeToken": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "chainIdIn": 137,
    "chainIdOut": 42161,
    "walletAddress": "0x9Ea7DbDA009D6fDeb0AEbF82c62F3CDC4A947098",
    "toAddress": "0x9Ea7DbDA009D6fDeb0AEbF82c62F3CDC4A947098",
    "expiresAt": "2024-11-26T18:54:30.000Z",
    "estimatedDurationInSeconds": 180,
    "txHashChainOut": "0x8e19cf256cdb95444ec3dea18eafd0fd833e838d7b2c9394125527592975a74c",
    "operationFee": "0.00002",
    "operationFeeReceiver": "0xcdb6d29a5f2f8d56af07588f5bea0e500b72548a",
    "provider": "XY"
  }
}

Breakdown of Payload Fields

event: The type of event notification (e.g., notification).
createdAt: Timestamp when the event occurred.
payload:
- id: Unique identifier for the event.
- txHash: Transaction hash for the event on the source chain.
- status: Current status of the transaction (e.g., COMPLETED).
- transactionType: Type of transaction (e.g., CROSS_SWAP).
- tokenIn: Token address used in the transaction.
- tokenOut: Token address received in the transaction.
- amountIn: Amount of tokenIn involved.
- amountOut: Amount of tokenOut received.
- chainIdIn: Chain ID for the source chain.
- chainIdOut: Chain ID for the destination chain.
- walletAddress: Address of the wallet that initiated the transaction.
- toAddress: Target address for the transaction.

Testing Your Webhook

To test your webhook:

Set up the endpoint as shown in the Quickstart.
Use tools like Postman or cURL to simulate POST requests to your endpoint with the example payload.
Verify that your signature validation works and that your application processes the events correctly.

Examples