TypeScript icon, indicating that this package has built-in type declarations

0.0.2 • Public • Published


Rest APIs leveraging HTTP protocol is the modern way of communicating between applications over the internet. Applications can communicate using a pull method or a push method. The pull method is inefficient in that, the receiver application needs to continuously poll the sender application for any updates or notifications that awaits to be communicated. The push method is efficient in that the receiver application registers a REST API with the sender application. Whenever there is an update or notification that needs to be sent to the receiver application, the sender invokes the registered REST API with appropriate data. This push method of REST API communication between applications is also called as webhooks.

The problem with communicating using webhook push notifications is that some applications are online with public IP, while some are behind firewalls and NAT without any public IP. Sometimes the application doesn't have an HTTP server implementation at all to handle the REST API.


SocketXP WebSocket Client allows applications to receive webhooks without public IP, re-configuring NAT/firewall or even having a web server in the first place. It does this by creating a sercure WebSocket tunnel (SSL/TLS connection) to the SocketXP Cloud Gateway( an online reverse proxy tunneling gateway run as a freemium SaaS service). SocketXP Cloud Gateway creates an unique public HTTP endpoint (URL) for each user. The user can use this public HTTP endpoint (URL) to register with any online webhook sender applications. The user application(webhook receiver), running in the local network behind firewall and NAT, could integrate with the SocketXP WebSocket Client library to receive the webhook notifications. The user application need not implement any HTTP server to receive the webhook notifications.


npm i socketxp-ws-client


To start using this library:

  1. Retrieve your auth token from SocketXP portal. You will need to supply them to the library.
  2. Create a SocketXP webhook relay tunnel named 'nodered' and check what input URL did you get (should be something like: Input URL will be your own webhook inbox that you can supply to any sender application to send webhooks or any HTTP requests to.
  3. Import the library into your application:
var ws = require(`socketxp-ws-client`);

// handler function has to accept a JSON string and parse on its own
var handler = function (data) {

// create a client with specified authtoken from and any webhook tunnels that
// can be created here Handler function is called whenever there's a new message
var client = new ws.SocketXPClient('your-auth-token', ['tunnel-1', 'tunnel-2'], handler)

// connect starts a websocket connection to SocketXP Cloud Gateway 

Example application

Set token as an environment variable:

// app.js
var ws = require(`socketxp-ws-client`);

var authtoken = process.env.SOCKETXP_TOKEN;

var handler = function (data) {

var socketxp = function () {    
    var client = new ws.SocketXPClient(authtoken, ['nodered'], handler)

    // do some work

    // disconnect whenever connection is no longer needed


To run it:

node app.js

Now, whenever webhooks are sent to your public endpoint<webhook-tunnel-name>, they will be received inside your application. You can subscribe to multiple webhook tunnels. Each message will have a JSON string in the following format that you can parse:

  "type": "webhook",             // event type
  "meta": {                      // webhook tunnels, input and output information 
    "webhook_tunnel_name": "my-webhook-tunnel-name",                                
    "input_name": "",
    "output_destination": "http://localhost:8080"
  "headers": {                   // request headers
    "Content-Type": [
  "query": "foo=bar",            // query (ie: /some-path?foo=bar)
  "body": "{\"hello\": \"world\"}", // request body
  "method": "POST"                // request method

Package Sidebar


npm i socketxp-ws-client

Weekly Downloads






Unpacked Size

58.1 kB

Total Files


Last publish


  • gvelrajan