DEV Community

Will Kennedy
Will Kennedy

Posted on • Originally published at brytelands.xyz on

Creating Solana webhooks with Helius, TypeScript and Rust

#solana #rust #webhooks #helius

Creating Solana webhooks with Helius, TypeScript and Rust

This tutorial will show you how easy it is to create your own webhook to tap into Solana events and send them to your applications, either parsed or in raw formats. Using webhooks is a great alternative to synchronous requests or websockets, especially if you aren't looking for two way communication.

All code for this tutorial can be found here:

https://github.com/wkennedy/helius-webhooks-tutorial

Overview of what you'll do in this tutorial

  • Create an ngrok account (https://ngrok.com/)
  • Create an account on Helius (https://www.helius.dev) in order to push data to the webhook you'll create
  • Create a simple application using TypeScript with an HTTP endpoint as the webhook.
  • (Optional) Create a simple application using Rust with an HTTP endpoint as the webhook.

Assumptions

  • You already have npm installed
  • You have cURL installed
  • (optional) You already have Rust installed.

Step 1 - Setup an ngrok account

Because we'll be running our webhook locally (localhost:3000/webhook), we need a way to tell Helius how to send a request to our localhost. There are several ways to do this, but the easiest is to use ngrok (https://ngrok.com/). Sign up is free and straightforward. Once you do that, you can download ngrok to your machine (Windows, MacOS, Linux). Once that is installed you can check to see if it's working:

 ngrok -v
Enter fullscreen mode Exit fullscreen mode

If that successfully prints the version you installed then you can run:

ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

After executing that command you should see something like this:

Forwarding https://3214-199-223-251-92.ngrok-free.app -> http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

This means, you can now use "https://3214-199-223-251-92.ngrok-free.app" and a public facing URL that will forward to your localhost. This URL is what we'll use to configure Helius.

Step 2 - Setup

This step will go over creating a webhook using the Helius UI, but an alternative is to do it programmatically using there SDK (https://github.com/helius-labs/helius-sdk#webhooks).

If you don't already have a Helius (https://www.helius.dev) account, you can create one for free. It will generate a project name for you and ask you to generate a new API key.

Creating Solana webhooks with Helius, TypeScript and Rust

Click the button and it will generate a new key and forward you to your new dashboard.

Creating Solana webhooks with Helius, TypeScript and Rust

You'll see two a devnet and mainnet URL that you can use for Solana RPC endpoints, but what we are interested in is the webhook functionality. Let's click on the webhook link in the navigation menu.

Creating Solana webhooks with Helius, TypeScript and Rust

Click the "New Webhook" button. Now we'll configure the webhook using the URL that ngrok provided, but with the addition of "/webhook": https://3214-199-223-251-92.ngrok-free.app/webhook

Creating Solana webhooks with Helius, TypeScript and Rust

The applications we'll make in next section will use "webhook" as the path for the HTTP endpoint.

Step 3 - Webhook (Node)

For this application, we'll create a simple web application using Express. The webapp will have a single POST endpoint, "/webhook", that will be called by Helius. Let's start by taking a look at the ts-app/package.json file. The application will need the following dependencies:

"dependencies": {  
  "@types/express": "^4.17.17",  
  "@types/node": "^20.4.8",  
  "body-parser": "^1.20.2",  
  "express": "^4.18.2",  
  "ts-node": "^10.9.1",  
  "typescript": "^5.1.6"  
}
Enter fullscreen mode Exit fullscreen mode

These dependencies will provide us with TypeScript support, the ability to deploy a web application using Express, and parse the request body as JSON.

If you haven't already, go ahead and do an npm install in the ts-app root to grab the node modules for the project.

cd /helius-webhooks-tutorial/ts-app
npm install
Enter fullscreen mode Exit fullscreen mode

Now let's take a look at the application itself:

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';

const app = express();
const port = 3000;

//We are expecting the body to contain valid JSON from the Helius request
app.use(bodyParser.json());

//This is our actual webhook that is served locally at http://localhost:3000/webhook.
//By using ngrok, the ngrok provided public url will map to our local webhook
//https://3214-199-223-251-92.ngrok-free.app/webhook -> http://localhost:3000/webhook
app.post('/webhook', (request: Request, response: Response) => {

    const requestBody = request.body;
    //Print the JSON to the console
    console.log('Data received by webook: ', requestBody);

    //Send a response that we received and processed the request.
    response.status(200).send('Webhook Request Received!');

});

app.listen(port, () => {
    console.log(`Server is running on port ${port}`);
});
Enter fullscreen mode Exit fullscreen mode

This is a simple application that listens for requests at http://localhost:3000/webhook and simply prints the JSON from the request body to the console. It's up to you what data you want from Helius and how to process it. For this example we are just going to use the test functionality from Helius.

Let's go ahead and start the web application:

npm run start-server
Enter fullscreen mode Exit fullscreen mode

You should see the following output:

> ts-app@1.0.0 start-server
> npx ts-node src/app.ts

Server is running on port 3000
Enter fullscreen mode Exit fullscreen mode

Before we test with Helius, we can check that everything is running okay locally. Issue the following cURL command:

curl --header "Content-Type: application/json" --request POST --data '{"key":"value"}' http://localhost:3000/webhook
Enter fullscreen mode Exit fullscreen mode

You should see the following output in the console:

Data received by webook: { key: 'value' }
Enter fullscreen mode Exit fullscreen mode

So far so good! The JSON we sent via cURL was successfully printed to the console like we expected. Now let's try it from Helius. On the webhook page, there is a button on the the far right where you see the webhook you created earlier. You can see it circled in yellow below. Click that link and approve the confirmation modal that pops up. You should see the following output in the console:

Data received by webook: [
  {
    blockTime: 1673445241,
    indexWithinBlock: 2557,
    meta: {
      err: null,
      fee: 10000,
      innerInstructions: [Array],
      loadedAddresses: [Array],
      logMessages: [Array],
      postBalances: [Array],
      postTokenBalances: [Array],
      preBalances: [Array],
      preTokenBalances: [Array],
      rewards: []
    },
    slot: 171942732,
    transaction: { message: [Array], signatures: [Array] }
  }
]
Enter fullscreen mode Exit fullscreen mode

You can now start requesting data from Helius for your use cases.

Step 4 - Webhook (Rust)

This is similar to Step 3, meaning all we're doing is creating a single POST endpoint to receive the Helius data. Let's start by taking a look at the dependencies in /rust-app/Cargo.toml.

warp = "0.3.5"  
serde = { version = "1.0.183", features = ["derive"] }  
serde_json = "1.0.104"  
tokio = { version = "1.30.0", features = ["rt-multi-thread", "macros"] }  
bytes = "1.4.0"
Enter fullscreen mode Exit fullscreen mode

The "warp" dependency is the web server to serve our webhook. Since warp handles requests asynchronously, tokio is needed to create an asynchronous runtime for warp to operate in. Lastly, serde is used to parse the request body into a JSON struct value.

In the /rust-app directory run:

cargo build
Enter fullscreen mode Exit fullscreen mode

This will download and build all the dependencies needed for this project.

Open the main.rs file in /rust-app/src:

use serde_json::Value;  
use warp::Filter;  
use warp::http::StatusCode;  

#[tokio::main]  
async fn main() {  
    //Create an HTTP POST endpoint "webhook" that takes the request body as bytes  
    //The bytes are then transformed into serde_json Value and printed to the console.  
    //If the JSON is valid, then a 200 code is returned   
    let webhook = warp::post()  
        .and(warp::path!("webhook"))  
        .and(warp::body::bytes())  
        .map(|bytes: bytes::Bytes| {  
            let v: Value = serde_json::from_slice(bytes.iter().as_slice()).expect("Error deserializing from slice");  
            println!("{}", v.to_string());  
            StatusCode::OK  
        });  

    //Create a simple healthcheck endpoint  
    let health_route = warp::path!("health")  
        .map(|| StatusCode::OK);  

    //Create the routes to pass to the server  
    let routes = health_route.or(webhook)  
        .with(warp::cors().allow_any_origin());  

    println!("Webhook Started!");  

    //Start the server on port 3000  
    warp::serve(routes).run(([127, 0, 0, 1], 3000)).await;  
}
Enter fullscreen mode Exit fullscreen mode

When this program is run, it creates a web application server running on port 3000, with two endpoints "/webhook" and "/health". To run the program type:

cargo run
Enter fullscreen mode Exit fullscreen mode

The console output will read:

Finished dev [unoptimized + debuginfo] target(s) in 0.03s
Running `target/debug/rust-app`
Webhook Started!
Enter fullscreen mode Exit fullscreen mode

We can test that our server is running correctly using the same cURL command as in step 3.

curl --header "Content-Type: application/json" --request POST --data '{"key":"value"}' http://localhost:3000/webhook
Enter fullscreen mode Exit fullscreen mode

In the console you'll see the following output:

{"key":"value"}
Enter fullscreen mode Exit fullscreen mode

Now let's try the Helius test button like we did in Step 3. The test output will be displayed in the console, in my case it looked like:

[
   {
      "accountData":[
         {
            "account":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
            "nativeBalanceChange":-72938049280,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"NTYeYJ1wr4bpM5xo6zx5En44SvJFAd35zTxxNoERYqd",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"AAaTGaA3uVqikfVEwoSG7EwkCb4bBDsMEyueiVUS5CaU",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"autMW8SgBkVYeBgqYiTuJZnkvDZMVU2MHJh9Jh7CSQ2",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"D8TxfGwdu9MiNMoJmUoC9wQfNfNT7Lnm6DzifQHRTy6B",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"5DxD5ViWjvRZEkxQEaJHZw2sBsso6xoXx3wGFNKgXUzE",
            "nativeBalanceChange":71860273440,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"25DTUAd1roBFoUQaxJQByL6Qy2cKQCBp4bK9sgfy9UiM",
            "nativeBalanceChange":-2039280,
            "tokenBalanceChanges":[
               {
                  "mint":"FdsNQE5EeCe57tbEYCRV1JwW5dzNCof7MUTaGWhmzYqu",
                  "rawTokenAmount":{
                     "decimals":0,
                     "tokenAmount":"-1"
                  },
                  "tokenAccount":"25DTUAd1roBFoUQaxJQByL6Qy2cKQCBp4bK9sgfy9UiM",
                  "userAccount":"1BWutmTvYPwDtmw9abTkS4Ssr8no61spGAvW1X6NDix"
               }
            ]
         },
         {
            "account":"DTYuh7gAGGZg2okM7hdFfU1yMY9LUemCiPyD5Z5GCs6Z",
            "nativeBalanceChange":2039280,
            "tokenBalanceChanges":[
               {
                  "mint":"FdsNQE5EeCe57tbEYCRV1JwW5dzNCof7MUTaGWhmzYqu",
                  "rawTokenAmount":{
                     "decimals":0,
                     "tokenAmount":"1"
                  },
                  "tokenAccount":"DTYuh7gAGGZg2okM7hdFfU1yMY9LUemCiPyD5Z5GCs6Z",
                  "userAccount":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX"
               }
            ]
         },
         {
            "account":"rFqFJ9g7TGBD8Ed7TPDnvGKZ5pWLPDyxLcvcH2eRCtt",
            "nativeBalanceChange":1080000000,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"CgXS5xC3qAGSg9txD9bS7BUgugZwshivGXpCJcGmdwrd",
            "nativeBalanceChange":-2234160,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"E8cU1WiRWjanGxmn96ewBgk9vPTcL6AEZ1t6F6fkgUWe",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"11111111111111111111111111111111",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"FdsNQE5EeCe57tbEYCRV1JwW5dzNCof7MUTaGWhmzYqu",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"AYZsWahcrSnkwqbA1ji7wEzgAnGjLNJhVUMDPfACECZf",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"SysvarRent111111111111111111111111111111111",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         },
         {
            "account":"1BWutmTvYPwDtmw9abTkS4Ssr8no61spGAvW1X6NDix",
            "nativeBalanceChange":0,
            "tokenBalanceChanges":[

            ]
         }
      ],
      "description":"5DxD5ViWjvRZEkxQEaJHZw2sBsso6xoXx3wGFNKgXUzE sold Fox #7637 to CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX for 72 SOL on MAGIC_EDEN.",
      "events":{
         "nft":{
            "amount":72000000000,
            "buyer":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
            "description":"5DxD5ViWjvRZEkxQEaJHZw2sBsso6xoXx3wGFNKgXUzE sold Fox #7637 to CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX for 72 SOL on MAGIC_EDEN.",
            "fee":10000,
            "feePayer":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
            "nfts":[
               {
                  "mint":"FdsNQE5EeCe57tbEYCRV1JwW5dzNCof7MUTaGWhmzYqu",
                  "tokenStandard":"NonFungible"
               }
            ],
            "saleType":"INSTANT_SALE",
            "seller":"5DxD5ViWjvRZEkxQEaJHZw2sBsso6xoXx3wGFNKgXUzE",
            "signature":"5nNtjezQMYBHvgSQmoRmJPiXGsPAWmJPoGSa64xanqrauogiVzFyGQhKeFataHGXq51jR2hjbzNTkPUpP787HAmL",
            "slot":171942732,
            "source":"MAGIC_EDEN",
            "staker":"",
            "timestamp":1673445241,
            "type":"NFT_SALE"
         }
      },
      "fee":10000,
      "feePayer":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
      "nativeTransfers":[
         {
            "amount":72936000000,
            "fromUserAccount":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
            "toUserAccount":"AAaTGaA3uVqikfVEwoSG7EwkCb4bBDsMEyueiVUS5CaU"
         },
         {
            "amount":2011440,
            "fromUserAccount":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
            "toUserAccount":"D8TxfGwdu9MiNMoJmUoC9wQfNfNT7Lnm6DzifQHRTy6B"
         },
         {
            "amount":71856000000,
            "fromUserAccount":"AAaTGaA3uVqikfVEwoSG7EwkCb4bBDsMEyueiVUS5CaU",
            "toUserAccount":"5DxD5ViWjvRZEkxQEaJHZw2sBsso6xoXx3wGFNKgXUzE"
         },
         {
            "amount":1080000000,
            "fromUserAccount":"AAaTGaA3uVqikfVEwoSG7EwkCb4bBDsMEyueiVUS5CaU",
            "toUserAccount":"rFqFJ9g7TGBD8Ed7TPDnvGKZ5pWLPDyxLcvcH2eRCtt"
         },
         {
            "amount":2039280,
            "fromUserAccount":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
            "toUserAccount":"DTYuh7gAGGZg2okM7hdFfU1yMY9LUemCiPyD5Z5GCs6Z"
         }
      ],
      "signature":"5nNtjezQMYBHvgSQmoRmJPiXGsPAWmJPoGSa64xanqrauogiVzFyGQhKeFataHGXq51jR2hjbzNTkPUpP787HAmL",
      "slot":171942732,
      "source":"MAGIC_EDEN",
      "timestamp":1673445241,
      "tokenTransfers":[
         {
            "fromTokenAccount":"25DTUAd1roBFoUQaxJQByL6Qy2cKQCBp4bK9sgfy9UiM",
            "fromUserAccount":"1BWutmTvYPwDtmw9abTkS4Ssr8no61spGAvW1X6NDix",
            "mint":"FdsNQE5EeCe57tbEYCRV1JwW5dzNCof7MUTaGWhmzYqu",
            "toTokenAccount":"DTYuh7gAGGZg2okM7hdFfU1yMY9LUemCiPyD5Z5GCs6Z",
            "toUserAccount":"CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX",
            "tokenAmount":1,
            "tokenStandard":"NonFungible"
         }
      ],
      "type":"NFT_SALE"
   }
]
Enter fullscreen mode Exit fullscreen mode

Now that you have the data, you can extract values, for example:

println!("{}", v[0]["type"]);  
println!("{}", v[0]["accountData"][0]);
Enter fullscreen mode Exit fullscreen mode

Alternatively, you can create a struct and use serde to transform the JSON payload into a struct for you to use in your application.

Top comments (0)

Read next

ckousik profile image

Kademlia - Routing - Part 1

Chinmay Kousik -

gaspardb profile image

What we learned building our SaaS with Rust 🦀

Gaspard Boursin -

crabnebuladev profile image

Recent Rust Security Advisory: CVE-2024-24576

CrabNebula -

atimin profile image

ReductStore CLI Client now in Rust

Alexey Timin -